From b5a1e3b8f4d95a54c398ba587b360ea0767d0bac Mon Sep 17 00:00:00 2001 From: Daniel Garnier-Moiroux Date: Fri, 27 Jun 2025 11:47:12 +0200 Subject: [PATCH 001/125] Add option for immediate execution in McpSyncServer - The McpSyncServer wraps an async server. By default, reactive operations are scheduled on a bounded-elastic scheduler, to offload blocking work and prevent accidental blocking of non-blocking operations. - With the default behavior, there will be thead ops, even in a blocking context, which means thread-locals from the request thread will be lost. This is inconenvient for frameworks that store state in thread-locals. - This commit adds the ability to avoid offloading, when the user is sure they are executing code in a blocking environment. Work happens in the calling thread, and thread-locals are available throughout the execution. --- .../server/McpServer.java | 25 +++++++- .../server/McpServerFeatures.java | 59 +++++++++++-------- .../server/McpSyncServer.java | 28 ++++++++- ...rverTransportProviderIntegrationTests.java | 38 +++++++++++- .../transport/McpTestServletFilter.java | 43 ++++++++++++++ .../server/transport/TomcatTestUtil.java | 13 ++++ 6 files changed, 172 insertions(+), 34 deletions(-) create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java index d6ec2cc30..637b7f92a 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java +++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java @@ -1,5 +1,5 @@ /* - * Copyright 2024-2024 the original author or authors. + * Copyright 2024-2025 the original author or authors. */ package io.modelcontextprotocol.server; @@ -695,6 +695,8 @@ class SyncSpecification { private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout + private boolean immediateExecution = false; + private SyncSpecification(McpServerTransportProvider transportProvider) { Assert.notNull(transportProvider, "Transport provider must not be null"); this.transportProvider = transportProvider; @@ -1116,6 +1118,22 @@ public SyncSpecification objectMapper(ObjectMapper objectMapper) { return this; } + /** + * Enable on "immediate execution" of the operations on the underlying + * {@link McpAsyncServer}. Defaults to false, which does blocking code offloading + * to prevent accidental blocking of the non-blocking transport. + *

+ * Do NOT set to true if the underlying transport is a non-blocking + * implementation. + * @param immediateExecution When true, do not offload work asynchronously. + * @return This builder instance for method chaining. + * + */ + public SyncSpecification immediateExecution(boolean immediateExecution) { + this.immediateExecution = immediateExecution; + return this; + } + /** * Builds a synchronous MCP server that provides blocking operations. * @return A new instance of {@link McpSyncServer} configured with this builder's @@ -1125,12 +1143,13 @@ public McpSyncServer build() { McpServerFeatures.Sync syncFeatures = new McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities, this.tools, this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers, this.instructions); - McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures); + McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures, + this.immediateExecution); var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper(); var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout, this.uriTemplateManagerFactory); - return new McpSyncServer(asyncServer); + return new McpSyncServer(asyncServer, this.immediateExecution); } } diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java index 8311f5d41..e61722a82 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java +++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java @@ -1,5 +1,5 @@ /* - * Copyright 2024-2024 the original author or authors. + * Copyright 2024-2025 the original author or authors. */ package io.modelcontextprotocol.server; @@ -95,28 +95,30 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s * blocking code offloading to prevent accidental blocking of the non-blocking * transport. * @param syncSpec a potentially blocking, synchronous specification. + * @param immediateExecution when true, do not offload. Do NOT set to true when + * using a non-blocking transport. * @return a specification which is protected from blocking calls specified by the * user. */ - static Async fromSync(Sync syncSpec) { + static Async fromSync(Sync syncSpec, boolean immediateExecution) { List tools = new ArrayList<>(); for (var tool : syncSpec.tools()) { - tools.add(AsyncToolSpecification.fromSync(tool)); + tools.add(AsyncToolSpecification.fromSync(tool, immediateExecution)); } Map resources = new HashMap<>(); syncSpec.resources().forEach((key, resource) -> { - resources.put(key, AsyncResourceSpecification.fromSync(resource)); + resources.put(key, AsyncResourceSpecification.fromSync(resource, immediateExecution)); }); Map prompts = new HashMap<>(); syncSpec.prompts().forEach((key, prompt) -> { - prompts.put(key, AsyncPromptSpecification.fromSync(prompt)); + prompts.put(key, AsyncPromptSpecification.fromSync(prompt, immediateExecution)); }); Map completions = new HashMap<>(); syncSpec.completions().forEach((key, completion) -> { - completions.put(key, AsyncCompletionSpecification.fromSync(completion)); + completions.put(key, AsyncCompletionSpecification.fromSync(completion, immediateExecution)); }); List, Mono>> rootChangeConsumers = new ArrayList<>(); @@ -239,15 +241,15 @@ record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities se public record AsyncToolSpecification(McpSchema.Tool tool, BiFunction, Mono> call) { - static AsyncToolSpecification fromSync(SyncToolSpecification tool) { + static AsyncToolSpecification fromSync(SyncToolSpecification tool, boolean immediate) { // FIXME: This is temporary, proper validation should be implemented if (tool == null) { return null; } - return new AsyncToolSpecification(tool.tool(), - (exchange, map) -> Mono - .fromCallable(() -> tool.call().apply(new McpSyncServerExchange(exchange), map)) - .subscribeOn(Schedulers.boundedElastic())); + return new AsyncToolSpecification(tool.tool(), (exchange, map) -> { + var toolResult = Mono.fromCallable(() -> tool.call().apply(new McpSyncServerExchange(exchange), map)); + return immediate ? toolResult : toolResult.subscribeOn(Schedulers.boundedElastic()); + }); } } @@ -281,15 +283,16 @@ static AsyncToolSpecification fromSync(SyncToolSpecification tool) { public record AsyncResourceSpecification(McpSchema.Resource resource, BiFunction> readHandler) { - static AsyncResourceSpecification fromSync(SyncResourceSpecification resource) { + static AsyncResourceSpecification fromSync(SyncResourceSpecification resource, boolean immediateExecution) { // FIXME: This is temporary, proper validation should be implemented if (resource == null) { return null; } - return new AsyncResourceSpecification(resource.resource(), - (exchange, req) -> Mono - .fromCallable(() -> resource.readHandler().apply(new McpSyncServerExchange(exchange), req)) - .subscribeOn(Schedulers.boundedElastic())); + return new AsyncResourceSpecification(resource.resource(), (exchange, req) -> { + var resourceResult = Mono + .fromCallable(() -> resource.readHandler().apply(new McpSyncServerExchange(exchange), req)); + return immediateExecution ? resourceResult : resourceResult.subscribeOn(Schedulers.boundedElastic()); + }); } } @@ -327,15 +330,16 @@ static AsyncResourceSpecification fromSync(SyncResourceSpecification resource) { public record AsyncPromptSpecification(McpSchema.Prompt prompt, BiFunction> promptHandler) { - static AsyncPromptSpecification fromSync(SyncPromptSpecification prompt) { + static AsyncPromptSpecification fromSync(SyncPromptSpecification prompt, boolean immediateExecution) { // FIXME: This is temporary, proper validation should be implemented if (prompt == null) { return null; } - return new AsyncPromptSpecification(prompt.prompt(), - (exchange, req) -> Mono - .fromCallable(() -> prompt.promptHandler().apply(new McpSyncServerExchange(exchange), req)) - .subscribeOn(Schedulers.boundedElastic())); + return new AsyncPromptSpecification(prompt.prompt(), (exchange, req) -> { + var promptResult = Mono + .fromCallable(() -> prompt.promptHandler().apply(new McpSyncServerExchange(exchange), req)); + return immediateExecution ? promptResult : promptResult.subscribeOn(Schedulers.boundedElastic()); + }); } } @@ -366,14 +370,17 @@ public record AsyncCompletionSpecification(McpSchema.CompleteReference reference * @return an asynchronous wrapper of the provided sync specification, or * {@code null} if input is null */ - static AsyncCompletionSpecification fromSync(SyncCompletionSpecification completion) { + static AsyncCompletionSpecification fromSync(SyncCompletionSpecification completion, + boolean immediateExecution) { if (completion == null) { return null; } - return new AsyncCompletionSpecification(completion.referenceKey(), - (exchange, request) -> Mono.fromCallable( - () -> completion.completionHandler().apply(new McpSyncServerExchange(exchange), request)) - .subscribeOn(Schedulers.boundedElastic())); + return new AsyncCompletionSpecification(completion.referenceKey(), (exchange, request) -> { + var completionResult = Mono.fromCallable( + () -> completion.completionHandler().apply(new McpSyncServerExchange(exchange), request)); + return immediateExecution ? completionResult + : completionResult.subscribeOn(Schedulers.boundedElastic()); + }); } } diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java index 91f8d9e4c..5adda1a74 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java +++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java @@ -54,13 +54,27 @@ public class McpSyncServer { */ private final McpAsyncServer asyncServer; + private final boolean immediateExecution; + /** * Creates a new synchronous server that wraps the provided async server. * @param asyncServer The async server to wrap */ public McpSyncServer(McpAsyncServer asyncServer) { + this(asyncServer, false); + } + + /** + * Creates a new synchronous server that wraps the provided async server. + * @param asyncServer The async server to wrap + * @param immediateExecution Tools, prompts, and resources handlers execute work + * without blocking code offloading. Do NOT set to true if the {@code asyncServer}'s + * transport is non-blocking. + */ + public McpSyncServer(McpAsyncServer asyncServer, boolean immediateExecution) { Assert.notNull(asyncServer, "Async server must not be null"); this.asyncServer = asyncServer; + this.immediateExecution = immediateExecution; } /** @@ -68,7 +82,9 @@ public McpSyncServer(McpAsyncServer asyncServer) { * @param toolHandler The tool handler to add */ public void addTool(McpServerFeatures.SyncToolSpecification toolHandler) { - this.asyncServer.addTool(McpServerFeatures.AsyncToolSpecification.fromSync(toolHandler)).block(); + this.asyncServer + .addTool(McpServerFeatures.AsyncToolSpecification.fromSync(toolHandler, this.immediateExecution)) + .block(); } /** @@ -84,7 +100,10 @@ public void removeTool(String toolName) { * @param resourceHandler The resource handler to add */ public void addResource(McpServerFeatures.SyncResourceSpecification resourceHandler) { - this.asyncServer.addResource(McpServerFeatures.AsyncResourceSpecification.fromSync(resourceHandler)).block(); + this.asyncServer + .addResource( + McpServerFeatures.AsyncResourceSpecification.fromSync(resourceHandler, this.immediateExecution)) + .block(); } /** @@ -100,7 +119,10 @@ public void removeResource(String resourceUri) { * @param promptSpecification The prompt specification to add */ public void addPrompt(McpServerFeatures.SyncPromptSpecification promptSpecification) { - this.asyncServer.addPrompt(McpServerFeatures.AsyncPromptSpecification.fromSync(promptSpecification)).block(); + this.asyncServer + .addPrompt( + McpServerFeatures.AsyncPromptSpecification.fromSync(promptSpecification, this.immediateExecution)) + .block(); } /** diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java index 4bd98b406..dcc7917d0 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java +++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java @@ -1,5 +1,5 @@ /* - * Copyright 2024 - 2024 the original author or authors. + * Copyright 2024 - 2025 the original author or authors. */ package io.modelcontextprotocol.server.transport; @@ -37,7 +37,6 @@ import org.apache.catalina.startup.Tomcat; import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Disabled; import org.junit.jupiter.api.Test; import reactor.core.publisher.Mono; import reactor.test.StepVerifier; @@ -46,6 +45,7 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatExceptionOfType; +import static org.assertj.core.api.InstanceOfAssertFactories.type; import static org.awaitility.Awaitility.await; import static org.mockito.Mockito.mock; @@ -728,6 +728,9 @@ void testToolCallSuccess() { var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification( new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + assertThat(McpTestServletFilter.getThreadLocalValue()) + .as("blocking code exectuion should be offloaded") + .isNull(); // perform a blocking call to a remote service String response = RestClient.create() .get() @@ -758,6 +761,37 @@ void testToolCallSuccess() { mcpServer.close(); } + @Test + void testToolCallImmediateExecution() { + McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification( + new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + var threadLocalValue = McpTestServletFilter.getThreadLocalValue(); + return CallToolResult.builder() + .addTextContent(threadLocalValue != null ? threadLocalValue : "") + .build(); + }); + + var mcpServer = McpServer.sync(mcpServerTransportProvider) + .capabilities(ServerCapabilities.builder().tools(true).build()) + .tools(tool1) + .immediateExecution(true) + .build(); + + try (var mcpClient = clientBuilder.build()) { + mcpClient.initialize(); + + CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())); + + assertThat(response).isNotNull(); + assertThat(response.content()).first() + .asInstanceOf(type(McpSchema.TextContent.class)) + .extracting(McpSchema.TextContent::text) + .isEqualTo(McpTestServletFilter.THREAD_LOCAL_VALUE); + } + + mcpServer.close(); + } + @Test void testToolListChangeHandlingSuccess() { diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java new file mode 100644 index 000000000..cc2543aa9 --- /dev/null +++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java @@ -0,0 +1,43 @@ +/* + * Copyright 2025 - 2025 the original author or authors. + */ + +package io.modelcontextprotocol.server.transport; + +import java.io.IOException; + +import jakarta.servlet.Filter; +import jakarta.servlet.FilterChain; +import jakarta.servlet.ServletException; +import jakarta.servlet.ServletRequest; +import jakarta.servlet.ServletResponse; + +/** + * Simple {@link Filter} which sets a value in a thread local. Used to verify whether MCP + * executions happen on the thread processing the request or are offloaded. + * + * @author Daniel Garnier-Moiroux + */ +public class McpTestServletFilter implements Filter { + + public static final String THREAD_LOCAL_VALUE = McpTestServletFilter.class.getName(); + + private static final ThreadLocal holder = new ThreadLocal<>(); + + @Override + public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) + throws IOException, ServletException { + holder.set(THREAD_LOCAL_VALUE); + try { + filterChain.doFilter(servletRequest, servletResponse); + } + finally { + holder.remove(); + } + } + + public static String getThreadLocalValue() { + return holder.get(); + } + +} diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java index f61cdc413..5a3928e02 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java +++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java @@ -10,9 +10,12 @@ import jakarta.servlet.Servlet; import org.apache.catalina.Context; import org.apache.catalina.startup.Tomcat; +import org.apache.tomcat.util.descriptor.web.FilterDef; +import org.apache.tomcat.util.descriptor.web.FilterMap; /** * @author Christian Tzolov + * @author Daniel Garnier-Moiroux */ public class TomcatTestUtil { @@ -39,6 +42,16 @@ public static Tomcat createTomcatServer(String contextPath, int port, Servlet se context.addChild(wrapper); context.addServletMappingDecoded("/*", "mcpServlet"); + var filterDef = new FilterDef(); + filterDef.setFilterClass(McpTestServletFilter.class.getName()); + filterDef.setFilterName(McpTestServletFilter.class.getSimpleName()); + context.addFilterDef(filterDef); + + var filterMap = new FilterMap(); + filterMap.setFilterName(McpTestServletFilter.class.getSimpleName()); + filterMap.addURLPattern("/*"); + context.addFilterMap(filterMap); + var connector = tomcat.getConnector(); connector.setAsyncTimeout(3000); From 9977a064d51f4e26f95a3bdc715c616b4a37dc64 Mon Sep 17 00:00:00 2001 From: bzsurbhi Date: Thu, 3 Jul 2025 11:43:28 -0700 Subject: [PATCH 002/125] feat: Add title field support to MCP schema classes (#372) - Add BaseMetadata interface with name() and title() methods for consistent metadata handling - The Prompt, PromptArgument, Resource, ResourceTemplate, ResuorceLink, PromptReference, Tool, and Implementation classes implement the BaseMetadata interface, adding a new, optional title field - Update constructors to support backward compatibility while allowing title specification - Modify ResourceContent interface to extend BaseMetadata - Update all test cases to accommodate new title parameter The title field provides human-readable display names optimized for UI contexts, while name remains for programmatic/logical use. This change maintains backward compatibility. Signed-off-by: Christian Tzolov Co-authored-by: Christian Tzolov --- .../WebFluxSseIntegrationTests.java | 9 +- .../client/AbstractMcpAsyncClientTests.java | 4 +- .../server/AbstractMcpAsyncServerTests.java | 4 +- .../server/AbstractMcpSyncServerTests.java | 4 +- .../server/McpAsyncServer.java | 7 +- .../modelcontextprotocol/spec/McpSchema.java | 1902 +++++++++-------- .../client/AbstractMcpAsyncClientTests.java | 4 +- .../McpAsyncClientResponseHandlerTests.java | 4 +- .../server/AbstractMcpAsyncServerTests.java | 4 +- .../server/AbstractMcpSyncServerTests.java | 4 +- .../spec/McpSchemaTests.java | 36 +- 11 files changed, 1053 insertions(+), 929 deletions(-) diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java index 73aff4629..c2ad1d68e 100644 --- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java +++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java @@ -996,11 +996,11 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) { var mcpServer = McpServer.sync(mcpServerTransportProvider) .capabilities(ServerCapabilities.builder().completions().build()) .prompts(new McpServerFeatures.SyncPromptSpecification( - new Prompt("code_review", "this is code review prompt", - List.of(new PromptArgument("language", "string", false))), + new Prompt("code_review", "Code review", "this is code review prompt", + List.of(new PromptArgument("language", "Language", "string", false))), (mcpSyncServerExchange, getPromptRequest) -> null)) .completions(new McpServerFeatures.SyncCompletionSpecification( - new McpSchema.PromptReference("ref/prompt", "code_review"), completionHandler)) + new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler)) .build(); try (var mcpClient = clientBuilder.build()) { @@ -1008,7 +1008,8 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) { InitializeResult initResult = mcpClient.initialize(); assertThat(initResult).isNotNull(); - CompleteRequest request = new CompleteRequest(new PromptReference("ref/prompt", "code_review"), + CompleteRequest request = new CompleteRequest( + new PromptReference("ref/prompt", "code_review", "Code review"), new CompleteRequest.CompleteArgument("language", "py")); CompleteResult result = mcpClient.completeCompletion(request); diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java index 9cccd3965..659a3222e 100644 --- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java +++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java @@ -420,7 +420,7 @@ void testListAllPromptsReturnsImmutableList() { .consumeNextWith(result -> { assertThat(result.prompts()).isNotNull(); // Verify that the returned list is immutable - assertThatThrownBy(() -> result.prompts().add(new Prompt("test", "test", null))) + assertThatThrownBy(() -> result.prompts().add(new Prompt("test", "Test", "test", null))) .isInstanceOf(UnsupportedOperationException.class); }) .verifyComplete(); @@ -604,7 +604,7 @@ void testListAllResourceTemplatesReturnsImmutableList() { assertThat(result.resourceTemplates()).isNotNull(); // Verify that the returned list is immutable assertThatThrownBy(() -> result.resourceTemplates() - .add(new McpSchema.ResourceTemplate("test://template", "test", null, null, null))) + .add(new McpSchema.ResourceTemplate("test://template", "test", "test", null, null, null))) .isInstanceOf(UnsupportedOperationException.class); }) .verifyComplete(); diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java index 12827f469..1f6730638 100644 --- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java +++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java @@ -302,7 +302,7 @@ void testAddPromptWithoutCapability() { .serverInfo("test-server", "1.0.0") .build(); - Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.AsyncPromptSpecification specification = new McpServerFeatures.AsyncPromptSpecification( prompt, (exchange, req) -> Mono.just(new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))))); @@ -330,7 +330,7 @@ void testRemovePromptWithoutCapability() { void testRemovePrompt() { String TEST_PROMPT_NAME_TO_REMOVE = "TEST_PROMPT_NAME678"; - Prompt prompt = new Prompt(TEST_PROMPT_NAME_TO_REMOVE, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME_TO_REMOVE, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.AsyncPromptSpecification specification = new McpServerFeatures.AsyncPromptSpecification( prompt, (exchange, req) -> Mono.just(new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))))); diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java index eefcdf9a3..5dac6f6a5 100644 --- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java +++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java @@ -289,7 +289,7 @@ void testAddPromptWithoutCapability() { .serverInfo("test-server", "1.0.0") .build(); - Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.SyncPromptSpecification specification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, req) -> new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))); @@ -310,7 +310,7 @@ void testRemovePromptWithoutCapability() { @Test void testRemovePrompt() { - Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.SyncPromptSpecification specification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, req) -> new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))); diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java index 02ad955b9..6efe58de4 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java +++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java @@ -462,8 +462,8 @@ private List getResourceTemplates() { .filter(uri -> uri.contains("{")) .map(uri -> { var resource = this.resources.get(uri).resource(); - var template = new McpSchema.ResourceTemplate(resource.uri(), resource.name(), resource.description(), - resource.mimeType(), resource.annotations()); + var template = new McpSchema.ResourceTemplate(resource.uri(), resource.name(), resource.title(), + resource.description(), resource.mimeType(), resource.annotations()); return template; }) .toList(); @@ -725,7 +725,8 @@ private McpSchema.CompleteRequest parseCompletionParams(Object object) { String refType = (String) refMap.get("type"); McpSchema.CompleteReference ref = switch (refType) { - case "ref/prompt" -> new McpSchema.PromptReference(refType, (String) refMap.get("name")); + case "ref/prompt" -> new McpSchema.PromptReference(refType, (String) refMap.get("name"), + refMap.get("title") != null ? (String) refMap.get("title") : null); case "ref/resource" -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri")); default -> throw new IllegalArgumentException("Invalid ref type: " + refType); }; diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java index 9be585cea..79534c87c 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java +++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java @@ -32,6 +32,7 @@ * * @author Christian Tzolov * @author Luca Chang + * @author Surbhi Bansal */ public final class McpSchema { @@ -203,40 +204,40 @@ public sealed interface JSONRPCMessage permits JSONRPCRequest, JSONRPCNotificati // TODO: batching support // @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY) public record JSONRPCRequest( // @formatter:off - @JsonProperty("jsonrpc") String jsonrpc, - @JsonProperty("method") String method, - @JsonProperty("id") Object id, - @JsonProperty("params") Object params) implements JSONRPCMessage { - } // @formatter:on + @JsonProperty("jsonrpc") String jsonrpc, + @JsonProperty("method") String method, + @JsonProperty("id") Object id, + @JsonProperty("params") Object params) implements JSONRPCMessage { + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) // TODO: batching support // @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY) public record JSONRPCNotification( // @formatter:off - @JsonProperty("jsonrpc") String jsonrpc, - @JsonProperty("method") String method, - @JsonProperty("params") Object params) implements JSONRPCMessage { - } // @formatter:on + @JsonProperty("jsonrpc") String jsonrpc, + @JsonProperty("method") String method, + @JsonProperty("params") Object params) implements JSONRPCMessage { + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) // TODO: batching support // @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY) public record JSONRPCResponse( // @formatter:off - @JsonProperty("jsonrpc") String jsonrpc, - @JsonProperty("id") Object id, - @JsonProperty("result") Object result, - @JsonProperty("error") JSONRPCError error) implements JSONRPCMessage { - - @JsonInclude(JsonInclude.Include.NON_ABSENT) - @JsonIgnoreProperties(ignoreUnknown = true) - public record JSONRPCError( - @JsonProperty("code") int code, - @JsonProperty("message") String message, - @JsonProperty("data") Object data) { - } - }// @formatter:on + @JsonProperty("jsonrpc") String jsonrpc, + @JsonProperty("id") Object id, + @JsonProperty("result") Object result, + @JsonProperty("error") JSONRPCError error) implements JSONRPCMessage { + + @JsonInclude(JsonInclude.Include.NON_ABSENT) + @JsonIgnoreProperties(ignoreUnknown = true) + public record JSONRPCError( + @JsonProperty("code") int code, + @JsonProperty("message") String message, + @JsonProperty("data") Object data) { + } + }// @formatter:on // --------------------------- // Initialization @@ -244,24 +245,24 @@ public record JSONRPCError( @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record InitializeRequest( // @formatter:off - @JsonProperty("protocolVersion") String protocolVersion, - @JsonProperty("capabilities") ClientCapabilities capabilities, - @JsonProperty("clientInfo") Implementation clientInfo, + @JsonProperty("protocolVersion") String protocolVersion, + @JsonProperty("capabilities") ClientCapabilities capabilities, + @JsonProperty("clientInfo") Implementation clientInfo, @JsonProperty("_meta") Map meta) implements Request { public InitializeRequest(String protocolVersion, ClientCapabilities capabilities, Implementation clientInfo) { this(protocolVersion, capabilities, clientInfo, null); } - } // @formatter:on + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record InitializeResult( // @formatter:off - @JsonProperty("protocolVersion") String protocolVersion, - @JsonProperty("capabilities") ServerCapabilities capabilities, - @JsonProperty("serverInfo") Implementation serverInfo, - @JsonProperty("instructions") String instructions) { - } // @formatter:on + @JsonProperty("protocolVersion") String protocolVersion, + @JsonProperty("capabilities") ServerCapabilities capabilities, + @JsonProperty("serverInfo") Implementation serverInfo, + @JsonProperty("instructions") String instructions) { + } // @formatter:on /** * Clients can implement additional features to enrich connected MCP servers with @@ -282,184 +283,198 @@ public record InitializeResult( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ClientCapabilities( // @formatter:off - @JsonProperty("experimental") Map experimental, - @JsonProperty("roots") RootCapabilities roots, - @JsonProperty("sampling") Sampling sampling, - @JsonProperty("elicitation") Elicitation elicitation) { - - /** - * Roots define the boundaries of where servers can operate within the filesystem, - * allowing them to understand which directories and files they have access to. - * Servers can request the list of roots from supporting clients and - * receive notifications when that list changes. - * - * @param listChanged Whether the client would send notification about roots - * has changed since the last time the server checked. - */ - @JsonInclude(JsonInclude.Include.NON_ABSENT) - @JsonIgnoreProperties(ignoreUnknown = true) - public record RootCapabilities( - @JsonProperty("listChanged") Boolean listChanged) { - } - - /** - * Provides a standardized way for servers to request LLM - * sampling ("completions" or "generations") from language - * models via clients. This flow allows clients to maintain - * control over model access, selection, and permissions - * while enabling servers to leverage AI capabilities—with - * no server API keys necessary. Servers can request text or - * image-based interactions and optionally include context - * from MCP servers in their prompts. - */ - @JsonInclude(JsonInclude.Include.NON_ABSENT) - public record Sampling() { - } - - /** - * Provides a standardized way for servers to request additional - * information from users through the client during interactions. - * This flow allows clients to maintain control over user - * interactions and data sharing while enabling servers to gather - * necessary information dynamically. Servers can request structured - * data from users with optional JSON schemas to validate responses. - */ - @JsonInclude(JsonInclude.Include.NON_ABSENT) - public record Elicitation() { - } - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private Map experimental; - private RootCapabilities roots; - private Sampling sampling; - private Elicitation elicitation; - - public Builder experimental(Map experimental) { - this.experimental = experimental; - return this; - } - - public Builder roots(Boolean listChanged) { - this.roots = new RootCapabilities(listChanged); - return this; - } - - public Builder sampling() { - this.sampling = new Sampling(); - return this; - } - - public Builder elicitation() { - this.elicitation = new Elicitation(); - return this; - } - - public ClientCapabilities build() { - return new ClientCapabilities(experimental, roots, sampling, elicitation); - } - } - }// @formatter:on + @JsonProperty("experimental") Map experimental, + @JsonProperty("roots") RootCapabilities roots, + @JsonProperty("sampling") Sampling sampling, + @JsonProperty("elicitation") Elicitation elicitation) { + + /** + * Roots define the boundaries of where servers can operate within the filesystem, + * allowing them to understand which directories and files they have access to. + * Servers can request the list of roots from supporting clients and + * receive notifications when that list changes. + * + * @param listChanged Whether the client would send notification about roots + * has changed since the last time the server checked. + */ + @JsonInclude(JsonInclude.Include.NON_ABSENT) + @JsonIgnoreProperties(ignoreUnknown = true) + public record RootCapabilities( + @JsonProperty("listChanged") Boolean listChanged) { + } + + /** + * Provides a standardized way for servers to request LLM + * sampling ("completions" or "generations") from language + * models via clients. This flow allows clients to maintain + * control over model access, selection, and permissions + * while enabling servers to leverage AI capabilities—with + * no server API keys necessary. Servers can request text or + * image-based interactions and optionally include context + * from MCP servers in their prompts. + */ + @JsonInclude(JsonInclude.Include.NON_ABSENT) + public record Sampling() { + } + + /** + * Provides a standardized way for servers to request additional + * information from users through the client during interactions. + * This flow allows clients to maintain control over user + * interactions and data sharing while enabling servers to gather + * necessary information dynamically. Servers can request structured + * data from users with optional JSON schemas to validate responses. + */ + @JsonInclude(JsonInclude.Include.NON_ABSENT) + public record Elicitation() { + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private Map experimental; + private RootCapabilities roots; + private Sampling sampling; + private Elicitation elicitation; + + public Builder experimental(Map experimental) { + this.experimental = experimental; + return this; + } + + public Builder roots(Boolean listChanged) { + this.roots = new RootCapabilities(listChanged); + return this; + } + + public Builder sampling() { + this.sampling = new Sampling(); + return this; + } + + public Builder elicitation() { + this.elicitation = new Elicitation(); + return this; + } + + public ClientCapabilities build() { + return new ClientCapabilities(experimental, roots, sampling, elicitation); + } + } + }// @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ServerCapabilities( // @formatter:off - @JsonProperty("completions") CompletionCapabilities completions, - @JsonProperty("experimental") Map experimental, - @JsonProperty("logging") LoggingCapabilities logging, - @JsonProperty("prompts") PromptCapabilities prompts, - @JsonProperty("resources") ResourceCapabilities resources, - @JsonProperty("tools") ToolCapabilities tools) { - - @JsonInclude(JsonInclude.Include.NON_ABSENT) - public record CompletionCapabilities() { - } - - @JsonInclude(JsonInclude.Include.NON_ABSENT) - public record LoggingCapabilities() { - } - - @JsonInclude(JsonInclude.Include.NON_ABSENT) - public record PromptCapabilities( - @JsonProperty("listChanged") Boolean listChanged) { - } - - @JsonInclude(JsonInclude.Include.NON_ABSENT) - public record ResourceCapabilities( - @JsonProperty("subscribe") Boolean subscribe, - @JsonProperty("listChanged") Boolean listChanged) { - } - - @JsonInclude(JsonInclude.Include.NON_ABSENT) - public record ToolCapabilities( - @JsonProperty("listChanged") Boolean listChanged) { - } - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - - private CompletionCapabilities completions; - private Map experimental; - private LoggingCapabilities logging = new LoggingCapabilities(); - private PromptCapabilities prompts; - private ResourceCapabilities resources; - private ToolCapabilities tools; - - public Builder completions() { - this.completions = new CompletionCapabilities(); - return this; - } - - public Builder experimental(Map experimental) { - this.experimental = experimental; - return this; - } - - public Builder logging() { - this.logging = new LoggingCapabilities(); - return this; - } - - public Builder prompts(Boolean listChanged) { - this.prompts = new PromptCapabilities(listChanged); - return this; - } - - public Builder resources(Boolean subscribe, Boolean listChanged) { - this.resources = new ResourceCapabilities(subscribe, listChanged); - return this; - } - - public Builder tools(Boolean listChanged) { - this.tools = new ToolCapabilities(listChanged); - return this; - } - - public ServerCapabilities build() { - return new ServerCapabilities(completions, experimental, logging, prompts, resources, tools); - } - } - } // @formatter:on + @JsonProperty("completions") CompletionCapabilities completions, + @JsonProperty("experimental") Map experimental, + @JsonProperty("logging") LoggingCapabilities logging, + @JsonProperty("prompts") PromptCapabilities prompts, + @JsonProperty("resources") ResourceCapabilities resources, + @JsonProperty("tools") ToolCapabilities tools) { + + @JsonInclude(JsonInclude.Include.NON_ABSENT) + public record CompletionCapabilities() { + } + @JsonInclude(JsonInclude.Include.NON_ABSENT) + public record LoggingCapabilities() { + } + + @JsonInclude(JsonInclude.Include.NON_ABSENT) + public record PromptCapabilities( + @JsonProperty("listChanged") Boolean listChanged) { + } + + @JsonInclude(JsonInclude.Include.NON_ABSENT) + public record ResourceCapabilities( + @JsonProperty("subscribe") Boolean subscribe, + @JsonProperty("listChanged") Boolean listChanged) { + } + + @JsonInclude(JsonInclude.Include.NON_ABSENT) + public record ToolCapabilities( + @JsonProperty("listChanged") Boolean listChanged) { + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + + private CompletionCapabilities completions; + private Map experimental; + private LoggingCapabilities logging = new LoggingCapabilities(); + private PromptCapabilities prompts; + private ResourceCapabilities resources; + private ToolCapabilities tools; + + public Builder completions() { + this.completions = new CompletionCapabilities(); + return this; + } + + public Builder experimental(Map experimental) { + this.experimental = experimental; + return this; + } + + public Builder logging() { + this.logging = new LoggingCapabilities(); + return this; + } + + public Builder prompts(Boolean listChanged) { + this.prompts = new PromptCapabilities(listChanged); + return this; + } + + public Builder resources(Boolean subscribe, Boolean listChanged) { + this.resources = new ResourceCapabilities(subscribe, listChanged); + return this; + } + + public Builder tools(Boolean listChanged) { + this.tools = new ToolCapabilities(listChanged); + return this; + } + + public ServerCapabilities build() { + return new ServerCapabilities(completions, experimental, logging, prompts, resources, tools); + } + } + } // @formatter:on + + /** + * Describes the name and version of an MCP implementation, with an optional title for + * UI representation. + * + * @param name Intended for programmatic or logical use, but used as a display name in + * past specs or fallback (if title isn't present). + * @param title Intended for UI and end-user contexts + * @param version The version of the implementation. + */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record Implementation(// @formatter:off - @JsonProperty("name") String name, - @JsonProperty("version") String version) { - } // @formatter:on + @JsonProperty("name") String name, + @JsonProperty("title") String title, + @JsonProperty("version") String version) implements BaseMetadata {// @formatter:on + + public Implementation(String name, String version) { + this(name, null, version); + } + } // Existing Enums and Base Types (from previous implementation) public enum Role {// @formatter:off - @JsonProperty("user") USER, - @JsonProperty("assistant") ASSISTANT - }// @formatter:on + @JsonProperty("user") USER, + @JsonProperty("assistant") ASSISTANT + }// @formatter:on // --------------------------- // Resource Interfaces @@ -489,9 +504,9 @@ public interface Annotated { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record Annotations( // @formatter:off - @JsonProperty("audience") List audience, - @JsonProperty("priority") Double priority) { - } // @formatter:on + @JsonProperty("audience") List audience, + @JsonProperty("priority") Double priority) { + } // @formatter:on /** * A common interface for resource content, which includes metadata about the resource @@ -499,12 +514,10 @@ public record Annotations( // @formatter:off * interface is implemented by both {@link Resource} and {@link ResourceLink} to * provide a consistent way to access resource metadata. */ - public interface ResourceContent { + public interface ResourceContent extends BaseMetadata { String uri(); - String name(); - String description(); String mimeType(); @@ -515,12 +528,35 @@ public interface ResourceContent { } + /** + * Base interface for metadata with name (identifier) and title (display name) + * properties. + */ + public interface BaseMetadata { + + /** + * Intended for programmatic or logical use, but used as a display name in past + * specs or fallback (if title isn't present). + */ + String name(); + + /** + * Intended for UI and end-user contexts — optimized to be human-readable and + * easily understood, even by those unfamiliar with domain-specific terminology. + * + * If not provided, the name should be used for display. + */ + String title(); + + } + /** * A known resource that the server is capable of reading. * * @param uri the URI of the resource. * @param name A human-readable name for this resource. This can be used by clients to * populate UI elements. + * @param title An optional title for this resource. * @param description A description of what this resource represents. This can be used * by clients to improve the LLM's understanding of available resources. It can be * thought of like a "hint" to the model. @@ -534,72 +570,87 @@ public interface ResourceContent { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record Resource( // @formatter:off - @JsonProperty("uri") String uri, - @JsonProperty("name") String name, - @JsonProperty("description") String description, - @JsonProperty("mimeType") String mimeType, - @JsonProperty("size") Long size, - @JsonProperty("annotations") Annotations annotations) implements Annotated, ResourceContent { - - /** - * @deprecated Only exists for backwards-compatibility purposes. Use - * {@link Resource#builder()} instead. - */ - @Deprecated - public Resource(String uri, String name, String description, String mimeType, Annotations annotations) { - this(uri, name, description, mimeType, null, annotations); - } - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private String uri; - private String name; - private String description; - private String mimeType; - private Long size; - private Annotations annotations; - - public Builder uri(String uri) { - this.uri = uri; - return this; - } - - public Builder name(String name) { - this.name = name; - return this; - } - - public Builder description(String description) { - this.description = description; - return this; - } - - public Builder mimeType(String mimeType) { - this.mimeType = mimeType; - return this; - } - - public Builder size(Long size) { - this.size = size; - return this; - } - - public Builder annotations(Annotations annotations) { - this.annotations = annotations; - return this; - } - - public Resource build() { - Assert.hasText(uri, "uri must not be empty"); - Assert.hasText(name, "name must not be empty"); - - return new Resource(uri, name, description, mimeType, size, annotations); - } - } - } // @formatter:on + @JsonProperty("uri") String uri, + @JsonProperty("name") String name, + @JsonProperty("title") String title, + @JsonProperty("description") String description, + @JsonProperty("mimeType") String mimeType, + @JsonProperty("size") Long size, + @JsonProperty("annotations") Annotations annotations) implements Annotated, ResourceContent {// @formatter:on + + /** + * @deprecated Only exists for backwards-compatibility purposes. Use + * {@link Resource#builder()} instead. + */ + @Deprecated + public Resource(String uri, String name, String description, String mimeType, Annotations annotations) { + this(uri, name, null, description, mimeType, null, annotations); + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + + private String uri; + + private String name; + + private String title; + + private String description; + + private String mimeType; + + private Long size; + + private Annotations annotations; + + public Builder uri(String uri) { + this.uri = uri; + return this; + } + + public Builder name(String name) { + this.name = name; + return this; + } + + public Builder title(String title) { + this.title = title; + return this; + } + + public Builder description(String description) { + this.description = description; + return this; + } + + public Builder mimeType(String mimeType) { + this.mimeType = mimeType; + return this; + } + + public Builder size(Long size) { + this.size = size; + return this; + } + + public Builder annotations(Annotations annotations) { + this.annotations = annotations; + return this; + } + + public Resource build() { + Assert.hasText(uri, "uri must not be empty"); + Assert.hasText(name, "name must not be empty"); + + return new Resource(uri, name, title, description, mimeType, size, annotations); + } + + } + } /** * Resource templates allow servers to expose parameterized resources using URI @@ -609,6 +660,7 @@ public Resource build() { * resource. * @param name A human-readable name for this resource. This can be used by clients to * populate UI elements. + * @param title An optional title for this resource. * @param description A description of what this resource represents. This can be used * by clients to improve the LLM's understanding of available resources. It can be * thought of like a "hint" to the model. @@ -620,43 +672,44 @@ public Resource build() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ResourceTemplate( // @formatter:off - @JsonProperty("uriTemplate") String uriTemplate, - @JsonProperty("name") String name, - @JsonProperty("description") String description, - @JsonProperty("mimeType") String mimeType, - @JsonProperty("annotations") Annotations annotations) implements Annotated { - } // @formatter:on + @JsonProperty("uriTemplate") String uriTemplate, + @JsonProperty("name") String name, + @JsonProperty("title") String title, + @JsonProperty("description") String description, + @JsonProperty("mimeType") String mimeType, + @JsonProperty("annotations") Annotations annotations) implements Annotated, BaseMetadata { + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ListResourcesResult( // @formatter:off - @JsonProperty("resources") List resources, - @JsonProperty("nextCursor") String nextCursor) { - } // @formatter:on + @JsonProperty("resources") List resources, + @JsonProperty("nextCursor") String nextCursor) { + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ListResourceTemplatesResult( // @formatter:off - @JsonProperty("resourceTemplates") List resourceTemplates, - @JsonProperty("nextCursor") String nextCursor) { - } // @formatter:on + @JsonProperty("resourceTemplates") List resourceTemplates, + @JsonProperty("nextCursor") String nextCursor) { + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ReadResourceRequest( // @formatter:off - @JsonProperty("uri") String uri, - @JsonProperty("_meta") Map meta) implements Request { + @JsonProperty("uri") String uri, + @JsonProperty("_meta") Map meta) implements Request {// @formatter:on - public ReadResourceRequest(String uri) { - this(uri, null); - } - } // @formatter:on + public ReadResourceRequest(String uri) { + this(uri, null); + } + } @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ReadResourceResult( // @formatter:off - @JsonProperty("contents") List contents){ - } // @formatter:on + @JsonProperty("contents") List contents){ + } // @formatter:on /** * Sent from the client to request resources/updated notifications from the server @@ -668,14 +721,14 @@ public record ReadResourceResult( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record SubscribeRequest( // @formatter:off - @JsonProperty("uri") String uri){ - } // @formatter:on + @JsonProperty("uri") String uri){ + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record UnsubscribeRequest( // @formatter:off - @JsonProperty("uri") String uri){ - } // @formatter:on + @JsonProperty("uri") String uri){ + } // @formatter:on /** * The contents of a specific resource or sub-resource. @@ -710,10 +763,10 @@ public sealed interface ResourceContents permits TextResourceContents, BlobResou @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record TextResourceContents( // @formatter:off - @JsonProperty("uri") String uri, - @JsonProperty("mimeType") String mimeType, - @JsonProperty("text") String text) implements ResourceContents { - } // @formatter:on + @JsonProperty("uri") String uri, + @JsonProperty("mimeType") String mimeType, + @JsonProperty("text") String text) implements ResourceContents { + } // @formatter:on /** * Binary contents of a resource. @@ -727,10 +780,10 @@ public record TextResourceContents( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record BlobResourceContents( // @formatter:off - @JsonProperty("uri") String uri, - @JsonProperty("mimeType") String mimeType, - @JsonProperty("blob") String blob) implements ResourceContents { - } // @formatter:on + @JsonProperty("uri") String uri, + @JsonProperty("mimeType") String mimeType, + @JsonProperty("blob") String blob) implements ResourceContents { + } // @formatter:on // --------------------------- // Prompt Interfaces @@ -739,31 +792,35 @@ public record BlobResourceContents( // @formatter:off * A prompt or prompt template that the server offers. * * @param name The name of the prompt or prompt template. + * @param title An optional title for the prompt. * @param description An optional description of what this prompt provides. * @param arguments A list of arguments to use for templating the prompt. */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record Prompt( // @formatter:off - @JsonProperty("name") String name, - @JsonProperty("description") String description, - @JsonProperty("arguments") List arguments) { - } // @formatter:on + @JsonProperty("name") String name, + @JsonProperty("title") String title, + @JsonProperty("description") String description, + @JsonProperty("arguments") List arguments) implements BaseMetadata { + } // @formatter:on /** * Describes an argument that a prompt can accept. * * @param name The name of the argument. + * @param title An optional title for the argument, which can be used in UI * @param description A human-readable description of the argument. * @param required Whether this argument must be provided. */ @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record PromptArgument( // @formatter:off - @JsonProperty("name") String name, - @JsonProperty("description") String description, - @JsonProperty("required") Boolean required) { - }// @formatter:on + @JsonProperty("name") String name, + @JsonProperty("title") String title, + @JsonProperty("description") String description, + @JsonProperty("required") Boolean required) implements BaseMetadata { + }// @formatter:on /** * Describes a message returned as part of a prompt. @@ -777,9 +834,9 @@ public record PromptArgument( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record PromptMessage( // @formatter:off - @JsonProperty("role") Role role, - @JsonProperty("content") Content content) { - } // @formatter:on + @JsonProperty("role") Role role, + @JsonProperty("content") Content content) { + } // @formatter:on /** * The server's response to a prompts/list request from the client. @@ -791,9 +848,9 @@ public record PromptMessage( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ListPromptsResult( // @formatter:off - @JsonProperty("prompts") List prompts, - @JsonProperty("nextCursor") String nextCursor) { - }// @formatter:on + @JsonProperty("prompts") List prompts, + @JsonProperty("nextCursor") String nextCursor) { + }// @formatter:on /** * Used by the client to get a prompt provided by the server. @@ -804,27 +861,27 @@ public record ListPromptsResult( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record GetPromptRequest(// @formatter:off - @JsonProperty("name") String name, - @JsonProperty("arguments") Map arguments, - @JsonProperty("_meta") Map meta) implements Request { - - public GetPromptRequest(String name, Map arguments) { - this(name, arguments, null); - } - }// @formatter:off - - /** - * The server's response to a prompts/get request from the client. - * - * @param description An optional description for the prompt. - * @param messages A list of messages to display as part of the prompt. - */ - @JsonInclude(JsonInclude.Include.NON_ABSENT) - @JsonIgnoreProperties(ignoreUnknown = true) - public record GetPromptResult( // @formatter:off - @JsonProperty("description") String description, - @JsonProperty("messages") List messages) { - } // @formatter:on + @JsonProperty("name") String name, + @JsonProperty("arguments") Map arguments, + @JsonProperty("_meta") Map meta) implements Request { + + public GetPromptRequest(String name, Map arguments) { + this(name, arguments, null); + } + }// @formatter:off + + /** + * The server's response to a prompts/get request from the client. + * + * @param description An optional description for the prompt. + * @param messages A list of messages to display as part of the prompt. + */ + @JsonInclude(JsonInclude.Include.NON_ABSENT) + @JsonIgnoreProperties(ignoreUnknown = true) + public record GetPromptResult( // @formatter:off + @JsonProperty("description") String description, + @JsonProperty("messages") List messages) { + } // @formatter:on // --------------------------- // Tool Interfaces @@ -839,20 +896,20 @@ public record GetPromptResult( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ListToolsResult( // @formatter:off - @JsonProperty("tools") List tools, - @JsonProperty("nextCursor") String nextCursor) { - }// @formatter:on + @JsonProperty("tools") List tools, + @JsonProperty("nextCursor") String nextCursor) { + }// @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record JsonSchema( // @formatter:off - @JsonProperty("type") String type, - @JsonProperty("properties") Map properties, - @JsonProperty("required") List required, - @JsonProperty("additionalProperties") Boolean additionalProperties, - @JsonProperty("$defs") Map defs, - @JsonProperty("definitions") Map definitions) { - } // @formatter:on + @JsonProperty("type") String type, + @JsonProperty("properties") Map properties, + @JsonProperty("required") List required, + @JsonProperty("additionalProperties") Boolean additionalProperties, + @JsonProperty("$defs") Map defs, + @JsonProperty("definitions") Map definitions) { + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) @@ -863,7 +920,7 @@ public record ToolAnnotations( // @formatter:off @JsonProperty("idempotentHint") Boolean idempotentHint, @JsonProperty("openWorldHint") Boolean openWorldHint, @JsonProperty("returnDirect") Boolean returnDirect) { - } // @formatter:on + } // @formatter:on /** * Represents a tool that the server provides. Tools enable servers to expose @@ -872,6 +929,7 @@ public record ToolAnnotations( // @formatter:off * * @param name A unique identifier for the tool. This name is used when calling the * tool. + * @param title A human-readable title for the tool. * @param description A human-readable description of what the tool does. This can be * used by clients to improve the LLM's understanding of available tools. * @param inputSchema A JSON Schema object that describes the expected structure of @@ -883,19 +941,69 @@ public record ToolAnnotations( // @formatter:off @JsonIgnoreProperties(ignoreUnknown = true) public record Tool( // @formatter:off @JsonProperty("name") String name, + @JsonProperty("title") String title, @JsonProperty("description") String description, @JsonProperty("inputSchema") JsonSchema inputSchema, - @JsonProperty("annotations") ToolAnnotations annotations) { + @JsonProperty("annotations") ToolAnnotations annotations) implements BaseMetadata { // @formatter:on + + public Tool(String name, String description, String schema) { + this(name, null, description, parseSchema(schema), null); + } + + public Tool(String name, String description, String schema, ToolAnnotations annotations) { + this(name, null, description, parseSchema(schema), annotations); + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + + private String name; + + private String title; + + private String description; + + private JsonSchema inputSchema; + + private ToolAnnotations annotations; + + public Builder name(String name) { + this.name = name; + return this; + } + + public Builder title(String title) { + this.title = title; + return this; + } + + public Builder description(String description) { + this.description = description; + return this; + } + + public Builder inputSchema(JsonSchema inputSchema) { + this.inputSchema = inputSchema; + return this; + } + + public Builder annotations(ToolAnnotations annotations) { + this.annotations = annotations; + return this; + } - public Tool(String name, String description, String schema) { - this(name, description, parseSchema(schema), null); - } + public Tool build() { + Assert.hasText(name, "name must not be empty"); - public Tool(String name, String description, String schema, ToolAnnotations annotations) { - this(name, description, parseSchema(schema), annotations); - } + return new Tool(name, title, description, inputSchema, annotations); + } - } // @formatter:on + } + + } private static JsonSchema parseSchema(String schema) { try { @@ -917,181 +1025,181 @@ private static JsonSchema parseSchema(String schema) { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record CallToolRequest(// @formatter:off - @JsonProperty("name") String name, - @JsonProperty("arguments") Map arguments, - @JsonProperty("_meta") Map meta) implements Request { - - public CallToolRequest(String name, String jsonArguments) { - this(name, parseJsonArguments(jsonArguments), null); - } - public CallToolRequest(String name, Map arguments) { - this(name, arguments, null); - } - - private static Map parseJsonArguments(String jsonArguments) { - try { - return OBJECT_MAPPER.readValue(jsonArguments, MAP_TYPE_REF); - } - catch (IOException e) { - throw new IllegalArgumentException("Invalid arguments: " + jsonArguments, e); - } - } - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private String name; - private Map arguments; - private Map meta; - - public Builder name(String name) { - this.name = name; - return this; - } - - public Builder arguments(Map arguments) { - this.arguments = arguments; - return this; - } - - public Builder arguments(String jsonArguments) { - this.arguments = parseJsonArguments(jsonArguments); - return this; - } - - public Builder meta(Map meta) { - this.meta = meta; - return this; - } - - public Builder progressToken(String progressToken) { - if (this.meta == null) { - this.meta = new HashMap<>(); - } - this.meta.put("progressToken", progressToken); - return this; - } - - public CallToolRequest build() { - Assert.hasText(name, "name must not be empty"); - return new CallToolRequest(name, arguments, meta); - } - } - }// @formatter:off - - /** - * The server's response to a tools/call request from the client. - * - * @param content A list of content items representing the tool's output. Each item can be text, an image, - * or an embedded resource. - * @param isError If true, indicates that the tool execution failed and the content contains error information. - * If false or absent, indicates successful execution. - */ - @JsonInclude(JsonInclude.Include.NON_ABSENT) - @JsonIgnoreProperties(ignoreUnknown = true) - public record CallToolResult( // @formatter:off - @JsonProperty("content") List content, - @JsonProperty("isError") Boolean isError) { - - /** - * Creates a new instance of {@link CallToolResult} with a string containing the - * tool result. - * - * @param content The content of the tool result. This will be mapped to a one-sized list - * with a {@link TextContent} element. - * @param isError If true, indicates that the tool execution failed and the content contains error information. - * If false or absent, indicates successful execution. - */ - public CallToolResult(String content, Boolean isError) { - this(List.of(new TextContent(content)), isError); - } - - /** - * Creates a builder for {@link CallToolResult}. - * @return a new builder instance - */ - public static Builder builder() { - return new Builder(); - } - - /** - * Builder for {@link CallToolResult}. - */ - public static class Builder { - private List content = new ArrayList<>(); - private Boolean isError; - - /** - * Sets the content list for the tool result. - * @param content the content list - * @return this builder - */ - public Builder content(List content) { - Assert.notNull(content, "content must not be null"); - this.content = content; - return this; - } - - /** - * Sets the text content for the tool result. - * @param textContent the text content - * @return this builder - */ - public Builder textContent(List textContent) { - Assert.notNull(textContent, "textContent must not be null"); - textContent.stream() - .map(TextContent::new) - .forEach(this.content::add); - return this; - } - - /** - * Adds a content item to the tool result. - * @param contentItem the content item to add - * @return this builder - */ - public Builder addContent(Content contentItem) { - Assert.notNull(contentItem, "contentItem must not be null"); - if (this.content == null) { - this.content = new ArrayList<>(); - } - this.content.add(contentItem); - return this; - } - - /** - * Adds a text content item to the tool result. - * @param text the text content - * @return this builder - */ - public Builder addTextContent(String text) { - Assert.notNull(text, "text must not be null"); - return addContent(new TextContent(text)); - } - - /** - * Sets whether the tool execution resulted in an error. - * @param isError true if the tool execution failed, false otherwise - * @return this builder - */ - public Builder isError(Boolean isError) { - Assert.notNull(isError, "isError must not be null"); - this.isError = isError; - return this; - } - - /** - * Builds a new {@link CallToolResult} instance. - * @return a new CallToolResult instance - */ - public CallToolResult build() { - return new CallToolResult(content, isError); - } - } - - } // @formatter:on + @JsonProperty("name") String name, + @JsonProperty("arguments") Map arguments, + @JsonProperty("_meta") Map meta) implements Request { + + public CallToolRequest(String name, String jsonArguments) { + this(name, parseJsonArguments(jsonArguments), null); + } + public CallToolRequest(String name, Map arguments) { + this(name, arguments, null); + } + + private static Map parseJsonArguments(String jsonArguments) { + try { + return OBJECT_MAPPER.readValue(jsonArguments, MAP_TYPE_REF); + } + catch (IOException e) { + throw new IllegalArgumentException("Invalid arguments: " + jsonArguments, e); + } + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private String name; + private Map arguments; + private Map meta; + + public Builder name(String name) { + this.name = name; + return this; + } + + public Builder arguments(Map arguments) { + this.arguments = arguments; + return this; + } + + public Builder arguments(String jsonArguments) { + this.arguments = parseJsonArguments(jsonArguments); + return this; + } + + public Builder meta(Map meta) { + this.meta = meta; + return this; + } + + public Builder progressToken(String progressToken) { + if (this.meta == null) { + this.meta = new HashMap<>(); + } + this.meta.put("progressToken", progressToken); + return this; + } + + public CallToolRequest build() { + Assert.hasText(name, "name must not be empty"); + return new CallToolRequest(name, arguments, meta); + } + } + }// @formatter:off + + /** + * The server's response to a tools/call request from the client. + * + * @param content A list of content items representing the tool's output. Each item can be text, an image, + * or an embedded resource. + * @param isError If true, indicates that the tool execution failed and the content contains error information. + * If false or absent, indicates successful execution. + */ + @JsonInclude(JsonInclude.Include.NON_ABSENT) + @JsonIgnoreProperties(ignoreUnknown = true) + public record CallToolResult( // @formatter:off + @JsonProperty("content") List content, + @JsonProperty("isError") Boolean isError) { + + /** + * Creates a new instance of {@link CallToolResult} with a string containing the + * tool result. + * + * @param content The content of the tool result. This will be mapped to a one-sized list + * with a {@link TextContent} element. + * @param isError If true, indicates that the tool execution failed and the content contains error information. + * If false or absent, indicates successful execution. + */ + public CallToolResult(String content, Boolean isError) { + this(List.of(new TextContent(content)), isError); + } + + /** + * Creates a builder for {@link CallToolResult}. + * @return a new builder instance + */ + public static Builder builder() { + return new Builder(); + } + + /** + * Builder for {@link CallToolResult}. + */ + public static class Builder { + private List content = new ArrayList<>(); + private Boolean isError; + + /** + * Sets the content list for the tool result. + * @param content the content list + * @return this builder + */ + public Builder content(List content) { + Assert.notNull(content, "content must not be null"); + this.content = content; + return this; + } + + /** + * Sets the text content for the tool result. + * @param textContent the text content + * @return this builder + */ + public Builder textContent(List textContent) { + Assert.notNull(textContent, "textContent must not be null"); + textContent.stream() + .map(TextContent::new) + .forEach(this.content::add); + return this; + } + + /** + * Adds a content item to the tool result. + * @param contentItem the content item to add + * @return this builder + */ + public Builder addContent(Content contentItem) { + Assert.notNull(contentItem, "contentItem must not be null"); + if (this.content == null) { + this.content = new ArrayList<>(); + } + this.content.add(contentItem); + return this; + } + + /** + * Adds a text content item to the tool result. + * @param text the text content + * @return this builder + */ + public Builder addTextContent(String text) { + Assert.notNull(text, "text must not be null"); + return addContent(new TextContent(text)); + } + + /** + * Sets whether the tool execution resulted in an error. + * @param isError true if the tool execution failed, false otherwise + * @return this builder + */ + public Builder isError(Boolean isError) { + Assert.notNull(isError, "isError must not be null"); + this.isError = isError; + return this; + } + + /** + * Builds a new {@link CallToolResult} instance. + * @return a new CallToolResult instance + */ + public CallToolResult build() { + return new CallToolResult(content, isError); + } + } + + } // @formatter:on // --------------------------- // Sampling Interfaces @@ -1099,53 +1207,53 @@ public CallToolResult build() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ModelPreferences(// @formatter:off - @JsonProperty("hints") List hints, - @JsonProperty("costPriority") Double costPriority, - @JsonProperty("speedPriority") Double speedPriority, - @JsonProperty("intelligencePriority") Double intelligencePriority) { - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private List hints; - private Double costPriority; - private Double speedPriority; - private Double intelligencePriority; - - public Builder hints(List hints) { - this.hints = hints; - return this; - } - - public Builder addHint(String name) { - if (this.hints == null) { - this.hints = new ArrayList<>(); - } - this.hints.add(new ModelHint(name)); - return this; - } - - public Builder costPriority(Double costPriority) { - this.costPriority = costPriority; - return this; - } - - public Builder speedPriority(Double speedPriority) { - this.speedPriority = speedPriority; - return this; - } - - public Builder intelligencePriority(Double intelligencePriority) { - this.intelligencePriority = intelligencePriority; - return this; - } - - public ModelPreferences build() { - return new ModelPreferences(hints, costPriority, speedPriority, intelligencePriority); - } - } + @JsonProperty("hints") List hints, + @JsonProperty("costPriority") Double costPriority, + @JsonProperty("speedPriority") Double speedPriority, + @JsonProperty("intelligencePriority") Double intelligencePriority) { + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private List hints; + private Double costPriority; + private Double speedPriority; + private Double intelligencePriority; + + public Builder hints(List hints) { + this.hints = hints; + return this; + } + + public Builder addHint(String name) { + if (this.hints == null) { + this.hints = new ArrayList<>(); + } + this.hints.add(new ModelHint(name)); + return this; + } + + public Builder costPriority(Double costPriority) { + this.costPriority = costPriority; + return this; + } + + public Builder speedPriority(Double speedPriority) { + this.speedPriority = speedPriority; + return this; + } + + public Builder intelligencePriority(Double intelligencePriority) { + this.intelligencePriority = intelligencePriority; + return this; + } + + public ModelPreferences build() { + return new ModelPreferences(hints, costPriority, speedPriority, intelligencePriority); + } + } } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @@ -1159,22 +1267,22 @@ public static ModelHint of(String name) { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record SamplingMessage(// @formatter:off - @JsonProperty("role") Role role, - @JsonProperty("content") Content content) { - } // @formatter:on + @JsonProperty("role") Role role, + @JsonProperty("content") Content content) { + } // @formatter:on // Sampling and Message Creation @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record CreateMessageRequest(// @formatter:off - @JsonProperty("messages") List messages, - @JsonProperty("modelPreferences") ModelPreferences modelPreferences, - @JsonProperty("systemPrompt") String systemPrompt, - @JsonProperty("includeContext") ContextInclusionStrategy includeContext, - @JsonProperty("temperature") Double temperature, - @JsonProperty("maxTokens") int maxTokens, - @JsonProperty("stopSequences") List stopSequences, - @JsonProperty("metadata") Map metadata, + @JsonProperty("messages") List messages, + @JsonProperty("modelPreferences") ModelPreferences modelPreferences, + @JsonProperty("systemPrompt") String systemPrompt, + @JsonProperty("includeContext") ContextInclusionStrategy includeContext, + @JsonProperty("temperature") Double temperature, + @JsonProperty("maxTokens") int maxTokens, + @JsonProperty("stopSequences") List stopSequences, + @JsonProperty("metadata") Map metadata, @JsonProperty("_meta") Map meta) implements Request { @@ -1187,66 +1295,66 @@ public CreateMessageRequest(List messages, ModelPreferences mod stopSequences, metadata, null); } - public enum ContextInclusionStrategy { - @JsonProperty("none") NONE, - @JsonProperty("thisServer") THIS_SERVER, - @JsonProperty("allServers") ALL_SERVERS - } - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private List messages; - private ModelPreferences modelPreferences; - private String systemPrompt; - private ContextInclusionStrategy includeContext; - private Double temperature; - private int maxTokens; - private List stopSequences; - private Map metadata; + public enum ContextInclusionStrategy { + @JsonProperty("none") NONE, + @JsonProperty("thisServer") THIS_SERVER, + @JsonProperty("allServers") ALL_SERVERS + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private List messages; + private ModelPreferences modelPreferences; + private String systemPrompt; + private ContextInclusionStrategy includeContext; + private Double temperature; + private int maxTokens; + private List stopSequences; + private Map metadata; private Map meta; - public Builder messages(List messages) { - this.messages = messages; - return this; - } - - public Builder modelPreferences(ModelPreferences modelPreferences) { - this.modelPreferences = modelPreferences; - return this; - } - - public Builder systemPrompt(String systemPrompt) { - this.systemPrompt = systemPrompt; - return this; - } - - public Builder includeContext(ContextInclusionStrategy includeContext) { - this.includeContext = includeContext; - return this; - } - - public Builder temperature(Double temperature) { - this.temperature = temperature; - return this; - } - - public Builder maxTokens(int maxTokens) { - this.maxTokens = maxTokens; - return this; - } - - public Builder stopSequences(List stopSequences) { - this.stopSequences = stopSequences; - return this; - } - - public Builder metadata(Map metadata) { - this.metadata = metadata; - return this; - } + public Builder messages(List messages) { + this.messages = messages; + return this; + } + + public Builder modelPreferences(ModelPreferences modelPreferences) { + this.modelPreferences = modelPreferences; + return this; + } + + public Builder systemPrompt(String systemPrompt) { + this.systemPrompt = systemPrompt; + return this; + } + + public Builder includeContext(ContextInclusionStrategy includeContext) { + this.includeContext = includeContext; + return this; + } + + public Builder temperature(Double temperature) { + this.temperature = temperature; + return this; + } + + public Builder maxTokens(int maxTokens) { + this.maxTokens = maxTokens; + return this; + } + + public Builder stopSequences(List stopSequences) { + this.stopSequences = stopSequences; + return this; + } + + public Builder metadata(Map metadata) { + this.metadata = metadata; + return this; + } public Builder meta(Map meta) { this.meta = meta; @@ -1261,82 +1369,82 @@ public Builder progressToken(String progressToken) { return this; } - public CreateMessageRequest build() { - return new CreateMessageRequest(messages, modelPreferences, systemPrompt, - includeContext, temperature, maxTokens, stopSequences, metadata, meta); - } - } - }// @formatter:on + public CreateMessageRequest build() { + return new CreateMessageRequest(messages, modelPreferences, systemPrompt, + includeContext, temperature, maxTokens, stopSequences, metadata, meta); + } + } + }// @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record CreateMessageResult(// @formatter:off - @JsonProperty("role") Role role, - @JsonProperty("content") Content content, - @JsonProperty("model") String model, - @JsonProperty("stopReason") StopReason stopReason) { - - public enum StopReason { - @JsonProperty("endTurn") END_TURN("endTurn"), - @JsonProperty("stopSequence") STOP_SEQUENCE("stopSequence"), - @JsonProperty("maxTokens") MAX_TOKENS("maxTokens"), - @JsonProperty("unknown") UNKNOWN("unknown"); - - private final String value; - - StopReason(String value) { - this.value = value; - } - - @JsonCreator - private static StopReason of(String value) { - return Arrays.stream(StopReason.values()) - .filter(stopReason -> stopReason.value.equals(value)) - .findFirst() - .orElse(StopReason.UNKNOWN); - } - } - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private Role role = Role.ASSISTANT; - private Content content; - private String model; - private StopReason stopReason = StopReason.END_TURN; - - public Builder role(Role role) { - this.role = role; - return this; - } - - public Builder content(Content content) { - this.content = content; - return this; - } - - public Builder model(String model) { - this.model = model; - return this; - } - - public Builder stopReason(StopReason stopReason) { - this.stopReason = stopReason; - return this; - } - - public Builder message(String message) { - this.content = new TextContent(message); - return this; - } - - public CreateMessageResult build() { - return new CreateMessageResult(role, content, model, stopReason); - } - } - }// @formatter:on + @JsonProperty("role") Role role, + @JsonProperty("content") Content content, + @JsonProperty("model") String model, + @JsonProperty("stopReason") StopReason stopReason) { + + public enum StopReason { + @JsonProperty("endTurn") END_TURN("endTurn"), + @JsonProperty("stopSequence") STOP_SEQUENCE("stopSequence"), + @JsonProperty("maxTokens") MAX_TOKENS("maxTokens"), + @JsonProperty("unknown") UNKNOWN("unknown"); + + private final String value; + + StopReason(String value) { + this.value = value; + } + + @JsonCreator + private static StopReason of(String value) { + return Arrays.stream(StopReason.values()) + .filter(stopReason -> stopReason.value.equals(value)) + .findFirst() + .orElse(StopReason.UNKNOWN); + } + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private Role role = Role.ASSISTANT; + private Content content; + private String model; + private StopReason stopReason = StopReason.END_TURN; + + public Builder role(Role role) { + this.role = role; + return this; + } + + public Builder content(Content content) { + this.content = content; + return this; + } + + public Builder model(String model) { + this.model = model; + return this; + } + + public Builder stopReason(StopReason stopReason) { + this.stopReason = stopReason; + return this; + } + + public Builder message(String message) { + this.content = new TextContent(message); + return this; + } + + public CreateMessageResult build() { + return new CreateMessageResult(role, content, model, stopReason); + } + } + }// @formatter:on // Elicitation /** @@ -1348,8 +1456,8 @@ public CreateMessageResult build() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ElicitRequest(// @formatter:off - @JsonProperty("message") String message, - @JsonProperty("requestedSchema") Map requestedSchema, + @JsonProperty("message") String message, + @JsonProperty("requestedSchema") Map requestedSchema, @JsonProperty("_meta") Map meta) implements Request { // backwards compatibility constructor @@ -1357,24 +1465,24 @@ public ElicitRequest(String message, Map requestedSchema) { this(message, requestedSchema, null); } - public static Builder builder() { - return new Builder(); - } + public static Builder builder() { + return new Builder(); + } - public static class Builder { - private String message; - private Map requestedSchema; + public static class Builder { + private String message; + private Map requestedSchema; private Map meta; - public Builder message(String message) { - this.message = message; - return this; - } + public Builder message(String message) { + this.message = message; + return this; + } - public Builder requestedSchema(Map requestedSchema) { - this.requestedSchema = requestedSchema; - return this; - } + public Builder requestedSchema(Map requestedSchema) { + this.requestedSchema = requestedSchema; + return this; + } public Builder meta(Map meta) { this.meta = meta; @@ -1389,47 +1497,47 @@ public Builder progressToken(String progressToken) { return this; } - public ElicitRequest build() { - return new ElicitRequest(message, requestedSchema, meta); - } - } - }// @formatter:on + public ElicitRequest build() { + return new ElicitRequest(message, requestedSchema, meta); + } + } + }// @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ElicitResult(// @formatter:off - @JsonProperty("action") Action action, - @JsonProperty("content") Map content) { - - public enum Action { - @JsonProperty("accept") ACCEPT, - @JsonProperty("decline") DECLINE, - @JsonProperty("cancel") CANCEL - } - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private Action action; - private Map content; - - public Builder message(Action action) { - this.action = action; - return this; - } - - public Builder content(Map content) { - this.content = content; - return this; - } - - public ElicitResult build() { - return new ElicitResult(action, content); - } - } - }// @formatter:on + @JsonProperty("action") Action action, + @JsonProperty("content") Map content) { + + public enum Action { + @JsonProperty("accept") ACCEPT, + @JsonProperty("decline") DECLINE, + @JsonProperty("cancel") CANCEL + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private Action action; + private Map content; + + public Builder message(Action action) { + this.action = action; + return this; + } + + public Builder content(Map content) { + this.content = content; + return this; + } + + public ElicitResult build() { + return new ElicitResult(action, content); + } + } + }// @formatter:on // --------------------------- // Pagination Interfaces @@ -1437,8 +1545,8 @@ public ElicitResult build() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record PaginatedRequest(// @formatter:off - @JsonProperty("cursor") String cursor, - @JsonProperty("_meta") Map meta) implements Request { // @formatter:on + @JsonProperty("cursor") String cursor, + @JsonProperty("_meta") Map meta) implements Request { // @formatter:on public PaginatedRequest(String cursor) { this(cursor, null); @@ -1474,11 +1582,11 @@ public record PaginatedResult(@JsonProperty("nextCursor") String nextCursor) { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ProgressNotification(// @formatter:off - @JsonProperty("progressToken") String progressToken, - @JsonProperty("progress") Double progress, - @JsonProperty("total") Double total, + @JsonProperty("progressToken") String progressToken, + @JsonProperty("progress") Double progress, + @JsonProperty("total") Double total, @JsonProperty("message") String message) { - }// @formatter:on + }// @formatter:on /** * The Model Context Protocol (MCP) provides a standardized way for servers to send @@ -1488,8 +1596,8 @@ public record ProgressNotification(// @formatter:off */ @JsonIgnoreProperties(ignoreUnknown = true) public record ResourcesUpdatedNotification(// @formatter:off - @JsonProperty("uri") String uri) { - }// @formatter:on + @JsonProperty("uri") String uri) { + }// @formatter:on /** * The Model Context Protocol (MCP) provides a standardized way for servers to send @@ -1503,61 +1611,61 @@ public record ResourcesUpdatedNotification(// @formatter:off */ @JsonIgnoreProperties(ignoreUnknown = true) public record LoggingMessageNotification(// @formatter:off - @JsonProperty("level") LoggingLevel level, - @JsonProperty("logger") String logger, - @JsonProperty("data") String data) { - - public static Builder builder() { - return new Builder(); - } - - public static class Builder { - private LoggingLevel level = LoggingLevel.INFO; - private String logger = "server"; - private String data; - - public Builder level(LoggingLevel level) { - this.level = level; - return this; - } - - public Builder logger(String logger) { - this.logger = logger; - return this; - } - - public Builder data(String data) { - this.data = data; - return this; - } - - public LoggingMessageNotification build() { - return new LoggingMessageNotification(level, logger, data); - } - } - }// @formatter:on + @JsonProperty("level") LoggingLevel level, + @JsonProperty("logger") String logger, + @JsonProperty("data") String data) { - public enum LoggingLevel {// @formatter:off - @JsonProperty("debug") DEBUG(0), - @JsonProperty("info") INFO(1), - @JsonProperty("notice") NOTICE(2), - @JsonProperty("warning") WARNING(3), - @JsonProperty("error") ERROR(4), - @JsonProperty("critical") CRITICAL(5), - @JsonProperty("alert") ALERT(6), - @JsonProperty("emergency") EMERGENCY(7); + public static Builder builder() { + return new Builder(); + } - private final int level; + public static class Builder { + private LoggingLevel level = LoggingLevel.INFO; + private String logger = "server"; + private String data; - LoggingLevel(int level) { - this.level = level; - } + public Builder level(LoggingLevel level) { + this.level = level; + return this; + } - public int level() { - return level; - } + public Builder logger(String logger) { + this.logger = logger; + return this; + } - } // @formatter:on + public Builder data(String data) { + this.data = data; + return this; + } + + public LoggingMessageNotification build() { + return new LoggingMessageNotification(level, logger, data); + } + } + }// @formatter:on + + public enum LoggingLevel {// @formatter:off + @JsonProperty("debug") DEBUG(0), + @JsonProperty("info") INFO(1), + @JsonProperty("notice") NOTICE(2), + @JsonProperty("warning") WARNING(3), + @JsonProperty("error") ERROR(4), + @JsonProperty("critical") CRITICAL(5), + @JsonProperty("alert") ALERT(6), + @JsonProperty("emergency") EMERGENCY(7); + + private final int level; + + LoggingLevel(int level) { + this.level = level; + } + + public int level() { + return level; + } + + } // @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) @@ -1578,61 +1686,62 @@ public sealed interface CompleteReference permits PromptReference, ResourceRefer @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record PromptReference(// @formatter:off - @JsonProperty("type") String type, - @JsonProperty("name") String name) implements McpSchema.CompleteReference { + @JsonProperty("type") String type, + @JsonProperty("name") String name, + @JsonProperty("title") String title ) implements McpSchema.CompleteReference, BaseMetadata { - public PromptReference(String name) { - this("ref/prompt", name); - } + public PromptReference(String name) { + this("ref/prompt", name, null); + } - @Override - public String identifier() { - return name(); - } - }// @formatter:on + @Override + public String identifier() { + return name(); + } + }// @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ResourceReference(// @formatter:off - @JsonProperty("type") String type, - @JsonProperty("uri") String uri) implements McpSchema.CompleteReference { + @JsonProperty("type") String type, + @JsonProperty("uri") String uri) implements McpSchema.CompleteReference { - public ResourceReference(String uri) { - this("ref/resource", uri); - } + public ResourceReference(String uri) { + this("ref/resource", uri); + } - @Override - public String identifier() { - return uri(); - } - }// @formatter:on + @Override + public String identifier() { + return uri(); + } + }// @formatter:on @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record CompleteRequest(// @formatter:off - @JsonProperty("ref") McpSchema.CompleteReference ref, - @JsonProperty("argument") CompleteArgument argument, - @JsonProperty("_meta") Map meta) implements Request { - - public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument) { - this(ref, argument, null); - } - - public record CompleteArgument( - @JsonProperty("name") String name, - @JsonProperty("value") String value) { - }// @formatter:on + @JsonProperty("ref") McpSchema.CompleteReference ref, + @JsonProperty("argument") CompleteArgument argument, + @JsonProperty("_meta") Map meta) implements Request { + + public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument) { + this(ref, argument, null); + } + + public record CompleteArgument( + @JsonProperty("name") String name, + @JsonProperty("value") String value) { + }// @formatter:on } @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record CompleteResult(@JsonProperty("completion") CompleteCompletion completion) { // @formatter:off - public record CompleteCompletion( - @JsonProperty("values") List values, - @JsonProperty("total") Integer total, - @JsonProperty("hasMore") Boolean hasMore) { - }// @formatter:on + public record CompleteCompletion( + @JsonProperty("values") List values, + @JsonProperty("total") Integer total, + @JsonProperty("hasMore") Boolean hasMore) { + }// @formatter:on } // --------------------------- @@ -1670,8 +1779,8 @@ else if (this instanceof ResourceLink) { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record TextContent( // @formatter:off - @JsonProperty("annotations") Annotations annotations, - @JsonProperty("text") String text) implements Annotated, Content { // @formatter:on + @JsonProperty("annotations") Annotations annotations, + @JsonProperty("text") String text) implements Annotated, Content { // @formatter:on public TextContent(String content) { this(null, content); @@ -1705,9 +1814,9 @@ public Double priority() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ImageContent( // @formatter:off - @JsonProperty("annotations") Annotations annotations, - @JsonProperty("data") String data, - @JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on + @JsonProperty("annotations") Annotations annotations, + @JsonProperty("data") String data, + @JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on /** * @deprecated Only exists for backwards-compatibility purposes. Use @@ -1737,16 +1846,16 @@ public Double priority() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record AudioContent( // @formatter:off - @JsonProperty("annotations") Annotations annotations, - @JsonProperty("data") String data, - @JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on + @JsonProperty("annotations") Annotations annotations, + @JsonProperty("data") String data, + @JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on } @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record EmbeddedResource( // @formatter:off - @JsonProperty("annotations") Annotations annotations, - @JsonProperty("resource") ResourceContents resource) implements Annotated, Content { // @formatter:on + @JsonProperty("annotations") Annotations annotations, + @JsonProperty("resource") ResourceContents resource) implements Annotated, Content { // @formatter:on /** * @deprecated Only exists for backwards-compatibility purposes. Use @@ -1780,6 +1889,7 @@ public Double priority() { * @param uri the URI of the resource. * @param name A human-readable name for this resource. This can be used by clients to * populate UI elements. + * @param title A human-readable title for this resource. * @param description A description of what this resource represents. This can be used * by clients to improve the LLM's understanding of available resources. It can be * thought of like a "hint" to the model. @@ -1793,12 +1903,13 @@ public Double priority() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ResourceLink( // @formatter:off - @JsonProperty("name") String name, - @JsonProperty("uri") String uri, - @JsonProperty("description") String description, - @JsonProperty("mimeType") String mimeType, - @JsonProperty("size") Long size, - @JsonProperty("annotations") Annotations annotations) implements Annotated, Content, ResourceContent { // @formatter:on + @JsonProperty("name") String name, + @JsonProperty("title") String title, + @JsonProperty("uri") String uri, + @JsonProperty("description") String description, + @JsonProperty("mimeType") String mimeType, + @JsonProperty("size") Long size, + @JsonProperty("annotations") Annotations annotations) implements Annotated, Content, ResourceContent { // @formatter:on public static Builder builder() { return new Builder(); @@ -1808,6 +1919,8 @@ public static class Builder { private String name; + private String title; + private String uri; private String description; @@ -1823,6 +1936,11 @@ public Builder name(String name) { return this; } + public Builder title(String title) { + this.title = title; + return this; + } + public Builder uri(String uri) { this.uri = uri; return this; @@ -1852,7 +1970,7 @@ public ResourceLink build() { Assert.hasText(uri, "uri must not be empty"); Assert.hasText(name, "name must not be empty"); - return new ResourceLink(name, uri, description, mimeType, size, annotations); + return new ResourceLink(name, title, uri, description, mimeType, size, annotations); } } @@ -1874,9 +1992,9 @@ public ResourceLink build() { @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record Root( // @formatter:off - @JsonProperty("uri") String uri, - @JsonProperty("name") String name) { - } // @formatter:on + @JsonProperty("uri") String uri, + @JsonProperty("name") String name) { + } // @formatter:on /** * The client's response to a roots/list request from the server. This result contains @@ -1892,12 +2010,12 @@ public record Root( // @formatter:off @JsonInclude(JsonInclude.Include.NON_ABSENT) @JsonIgnoreProperties(ignoreUnknown = true) public record ListRootsResult( // @formatter:off - @JsonProperty("roots") List roots, - @JsonProperty("nextCursor") String nextCursor) { + @JsonProperty("roots") List roots, + @JsonProperty("nextCursor") String nextCursor) { - public ListRootsResult(List roots) { - this(roots, null); - } - } // @formatter:on + public ListRootsResult(List roots) { + this(roots, null); + } + } // @formatter:on } diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java index a3edda2b9..154937d21 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java +++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java @@ -421,7 +421,7 @@ void testListAllPromptsReturnsImmutableList() { .consumeNextWith(result -> { assertThat(result.prompts()).isNotNull(); // Verify that the returned list is immutable - assertThatThrownBy(() -> result.prompts().add(new Prompt("test", "test", null))) + assertThatThrownBy(() -> result.prompts().add(new Prompt("test", "test", "test", null))) .isInstanceOf(UnsupportedOperationException.class); }) .verifyComplete(); @@ -605,7 +605,7 @@ void testListAllResourceTemplatesReturnsImmutableList() { assertThat(result.resourceTemplates()).isNotNull(); // Verify that the returned list is immutable assertThatThrownBy(() -> result.resourceTemplates() - .add(new McpSchema.ResourceTemplate("test://template", "test", null, null, null))) + .add(new McpSchema.ResourceTemplate("test://template", "test", "test", null, null, null))) .isInstanceOf(UnsupportedOperationException.class); }) .verifyComplete(); diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java index 3e89c8cef..e773c8381 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java +++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java @@ -251,8 +251,8 @@ void testPromptsChangeNotificationHandling() { assertThat(asyncMcpClient.initialize().block()).isNotNull(); // Create a mock prompts list that the server will return - McpSchema.Prompt mockPrompt = new McpSchema.Prompt("test-prompt", "Test Prompt Description", - List.of(new McpSchema.PromptArgument("arg1", "Test argument", true))); + McpSchema.Prompt mockPrompt = new McpSchema.Prompt("test-prompt", "Test Prompt", "Test Prompt Description", + List.of(new McpSchema.PromptArgument("arg1", "Test argument", "Test argument", true))); McpSchema.ListPromptsResult mockPromptsResult = new McpSchema.ListPromptsResult(List.of(mockPrompt), null); // Simulate server sending prompts/list_changed notification diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java index dd9f65895..41bf0e640 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java +++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java @@ -301,7 +301,7 @@ void testAddPromptWithoutCapability() { .serverInfo("test-server", "1.0.0") .build(); - Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.AsyncPromptSpecification specification = new McpServerFeatures.AsyncPromptSpecification( prompt, (exchange, req) -> Mono.just(new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))))); @@ -329,7 +329,7 @@ void testRemovePromptWithoutCapability() { void testRemovePrompt() { String TEST_PROMPT_NAME_TO_REMOVE = "TEST_PROMPT_NAME678"; - Prompt prompt = new Prompt(TEST_PROMPT_NAME_TO_REMOVE, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME_TO_REMOVE, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.AsyncPromptSpecification specification = new McpServerFeatures.AsyncPromptSpecification( prompt, (exchange, req) -> Mono.just(new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))))); diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java index 6cbb8632c..8a79e3427 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java +++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java @@ -288,7 +288,7 @@ void testAddPromptWithoutCapability() { .serverInfo("test-server", "1.0.0") .build(); - Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.SyncPromptSpecification specification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, req) -> new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))); @@ -309,7 +309,7 @@ void testRemovePromptWithoutCapability() { @Test void testRemovePrompt() { - Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", List.of()); + Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of()); McpServerFeatures.SyncPromptSpecification specification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, req) -> new GetPromptResult("Test prompt description", List .of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))); diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java index ea063e4e3..786be3294 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java +++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java @@ -207,8 +207,8 @@ void testEmbeddedResourceWithBlobContentsDeserialization() throws Exception { @Test void testResourceLink() throws Exception { - McpSchema.ResourceLink resourceLink = new McpSchema.ResourceLink("main.rs", "file:///project/src/main.rs", - "Primary application entry point", "text/x-rust", null, null); + McpSchema.ResourceLink resourceLink = new McpSchema.ResourceLink("main.rs", "Main file", + "file:///project/src/main.rs", "Primary application entry point", "text/x-rust", null, null); String value = mapper.writeValueAsString(resourceLink); assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER) @@ -216,7 +216,7 @@ void testResourceLink() throws Exception { .isObject() .isEqualTo( json(""" - {"type":"resource_link","name":"main.rs","uri":"file:///project/src/main.rs","description":"Primary application entry point","mimeType":"text/x-rust"}""")); + {"type":"resource_link","name":"main.rs","title":"Main file","uri":"file:///project/src/main.rs","description":"Primary application entry point","mimeType":"text/x-rust"}""")); } @Test @@ -419,7 +419,7 @@ void testResourceTemplate() throws Exception { McpSchema.Annotations annotations = new McpSchema.Annotations(Arrays.asList(McpSchema.Role.USER), 0.5); McpSchema.ResourceTemplate template = new McpSchema.ResourceTemplate("resource://{param}/test", "Test Template", - "A test resource template", "text/plain", annotations); + "Test Template", "A test resource template", "text/plain", annotations); String value = mapper.writeValueAsString(template); assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER) @@ -427,7 +427,7 @@ void testResourceTemplate() throws Exception { .isObject() .isEqualTo( json(""" - {"uriTemplate":"resource://{param}/test","name":"Test Template","description":"A test resource template","mimeType":"text/plain","annotations":{"audience":["user"],"priority":0.5}}""")); + {"uriTemplate":"resource://{param}/test","name":"Test Template","title":"Test Template","description":"A test resource template","mimeType":"text/plain","annotations":{"audience":["user"],"priority":0.5}}""")); } @Test @@ -453,10 +453,10 @@ void testListResourcesResult() throws Exception { @Test void testListResourceTemplatesResult() throws Exception { McpSchema.ResourceTemplate template1 = new McpSchema.ResourceTemplate("resource://{param}/test1", - "Test Template 1", "First test template", "text/plain", null); + "Test Template 1", "Test Template 1", "First test template", "text/plain", null); McpSchema.ResourceTemplate template2 = new McpSchema.ResourceTemplate("resource://{param}/test2", - "Test Template 2", "Second test template", "application/json", null); + "Test Template 2", "Test Template 2", "Second test template", "application/json", null); McpSchema.ListResourceTemplatesResult result = new McpSchema.ListResourceTemplatesResult( Arrays.asList(template1, template2), "next-cursor"); @@ -467,7 +467,7 @@ void testListResourceTemplatesResult() throws Exception { .isObject() .isEqualTo( json(""" - {"resourceTemplates":[{"uriTemplate":"resource://{param}/test1","name":"Test Template 1","description":"First test template","mimeType":"text/plain"},{"uriTemplate":"resource://{param}/test2","name":"Test Template 2","description":"Second test template","mimeType":"application/json"}],"nextCursor":"next-cursor"}""")); + {"resourceTemplates":[{"uriTemplate":"resource://{param}/test1","name":"Test Template 1","title":"Test Template 1","description":"First test template","mimeType":"text/plain"},{"uriTemplate":"resource://{param}/test2","name":"Test Template 2","title":"Test Template 2","description":"Second test template","mimeType":"application/json"}],"nextCursor":"next-cursor"}""")); } @Test @@ -535,11 +535,13 @@ void testReadResourceResult() throws Exception { @Test void testPrompt() throws Exception { - McpSchema.PromptArgument arg1 = new McpSchema.PromptArgument("arg1", "First argument", true); + McpSchema.PromptArgument arg1 = new McpSchema.PromptArgument("arg1", "First argument", "First argument", true); - McpSchema.PromptArgument arg2 = new McpSchema.PromptArgument("arg2", "Second argument", false); + McpSchema.PromptArgument arg2 = new McpSchema.PromptArgument("arg2", "Second argument", "Second argument", + false); - McpSchema.Prompt prompt = new McpSchema.Prompt("test-prompt", "A test prompt", Arrays.asList(arg1, arg2)); + McpSchema.Prompt prompt = new McpSchema.Prompt("test-prompt", "Test Prompt", "A test prompt", + Arrays.asList(arg1, arg2)); String value = mapper.writeValueAsString(prompt); assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER) @@ -547,7 +549,7 @@ void testPrompt() throws Exception { .isObject() .isEqualTo( json(""" - {"name":"test-prompt","description":"A test prompt","arguments":[{"name":"arg1","description":"First argument","required":true},{"name":"arg2","description":"Second argument","required":false}]}""")); + {"name":"test-prompt","title":"Test Prompt","description":"A test prompt","arguments":[{"name":"arg1","title":"First argument","description":"First argument","required":true},{"name":"arg2","title":"Second argument","description":"Second argument","required":false}]}""")); } @Test @@ -566,11 +568,13 @@ void testPromptMessage() throws Exception { @Test void testListPromptsResult() throws Exception { - McpSchema.PromptArgument arg = new McpSchema.PromptArgument("arg", "An argument", true); + McpSchema.PromptArgument arg = new McpSchema.PromptArgument("arg", "Argument", "An argument", true); - McpSchema.Prompt prompt1 = new McpSchema.Prompt("prompt1", "First prompt", Collections.singletonList(arg)); + McpSchema.Prompt prompt1 = new McpSchema.Prompt("prompt1", "First prompt", "First prompt", + Collections.singletonList(arg)); - McpSchema.Prompt prompt2 = new McpSchema.Prompt("prompt2", "Second prompt", Collections.emptyList()); + McpSchema.Prompt prompt2 = new McpSchema.Prompt("prompt2", "Second prompt", "Second prompt", + Collections.emptyList()); McpSchema.ListPromptsResult result = new McpSchema.ListPromptsResult(Arrays.asList(prompt1, prompt2), "next-cursor"); @@ -581,7 +585,7 @@ void testListPromptsResult() throws Exception { .isObject() .isEqualTo( json(""" - {"prompts":[{"name":"prompt1","description":"First prompt","arguments":[{"name":"arg","description":"An argument","required":true}]},{"name":"prompt2","description":"Second prompt","arguments":[]}],"nextCursor":"next-cursor"}""")); + {"prompts":[{"name":"prompt1","title":"First prompt","description":"First prompt","arguments":[{"name":"arg","title":"Argument","description":"An argument","required":true}]},{"name":"prompt2","title":"Second prompt","description":"Second prompt","arguments":[]}],"nextCursor":"next-cursor"}""")); } @Test From b37c32cdbaac01963298a05d745d0f8d2085bc0d Mon Sep 17 00:00:00 2001 From: Christian Tzolov Date: Thu, 3 Jul 2025 15:01:16 +0200 Subject: [PATCH 003/125] refactor: extract MCP client initialization logic into LifecycleInitializer (#370) - Create new LifecycleInitializer class to handle protocol initialization phase - Move initialization logic from McpAsyncClient to dedicated initializer - Add javadocs for MCP initialization process - Implement protocol version negotiation and capability exchange - Add exception handling for transport session recovery - Include test suite for LifecyleInitializer - Simplify McpAsyncClient by delegating initialization responsibilities This refactoring improves separation of concerns and makes the initialization process more maintainable and testable. Signed-off-by: Christian Tzolov --- .../client/LifecycleInitializer.java | 348 +++++++++++++++ .../client/McpAsyncClient.java | 222 ++-------- .../client/LifecycleInitializerTests.java | 412 ++++++++++++++++++ 3 files changed, 795 insertions(+), 187 deletions(-) create mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java create mode 100644 mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java new file mode 100644 index 000000000..e33fafa6a --- /dev/null +++ b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java @@ -0,0 +1,348 @@ +package io.modelcontextprotocol.client; + +import java.time.Duration; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.Function; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import io.modelcontextprotocol.spec.McpClientSession; +import io.modelcontextprotocol.spec.McpError; +import io.modelcontextprotocol.spec.McpSchema; +import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException; +import io.modelcontextprotocol.util.Assert; +import reactor.core.publisher.Mono; +import reactor.core.publisher.Sinks; +import reactor.util.context.ContextView; + +/** + * Handles the protocol initialization phase between client and server + * + *

+ * The initialization phase MUST be the first interaction between client and server. + * During this phase, the client and server perform the following operations: + *

+ * + * Client Initialization Process + *

+ * The client MUST initiate this phase by sending an initialize request containing: + *

+ * + *

+ * After successful initialization, the client MUST send an initialized notification to + * indicate it is ready to begin normal operations. + * + * Server Response + *

+ * The server MUST respond with its own capabilities and information. + * + * Protocol Version Negotiation + *

+ * In the initialize request, the client MUST send a protocol version it supports. This + * SHOULD be the latest version supported by the client. + * + *

+ * If the server supports the requested protocol version, it MUST respond with the same + * version. Otherwise, the server MUST respond with another protocol version it supports. + * This SHOULD be the latest version supported by the server. + * + *

+ * If the client does not support the version in the server's response, it SHOULD + * disconnect. + * + * Request Restrictions + *

+ * Important: The following restrictions apply during initialization: + *

+ */ +class LifecycleInitializer { + + private static final Logger logger = LoggerFactory.getLogger(LifecycleInitializer.class); + + /** + * The MCP session supplier that manages bidirectional JSON-RPC communication between + * clients and servers. + */ + private final Function sessionSupplier; + + private final McpSchema.ClientCapabilities clientCapabilities; + + private final McpSchema.Implementation clientInfo; + + private List protocolVersions; + + private final AtomicReference initializationRef = new AtomicReference<>(); + + /** + * The max timeout to await for the client-server connection to be initialized. + */ + private final Duration initializationTimeout; + + public LifecycleInitializer(McpSchema.ClientCapabilities clientCapabilities, McpSchema.Implementation clientInfo, + List protocolVersions, Duration initializationTimeout, + Function sessionSupplier) { + + Assert.notNull(sessionSupplier, "Session supplier must not be null"); + Assert.notNull(clientCapabilities, "Client capabilities must not be null"); + Assert.notNull(clientInfo, "Client info must not be null"); + Assert.notEmpty(protocolVersions, "Protocol versions must not be empty"); + Assert.notNull(initializationTimeout, "Initialization timeout must not be null"); + + this.sessionSupplier = sessionSupplier; + this.clientCapabilities = clientCapabilities; + this.clientInfo = clientInfo; + this.protocolVersions = Collections.unmodifiableList(new ArrayList<>(protocolVersions)); + this.initializationTimeout = initializationTimeout; + } + + /** + * This method is package-private and used for test only. Should not be called by user + * code. + * @param protocolVersions the Client supported protocol versions. + */ + void setProtocolVersions(List protocolVersions) { + this.protocolVersions = protocolVersions; + } + + /** + * Represents the initialization state of the MCP client. + */ + interface Initialization { + + /** + * Returns the MCP client session that is used to communicate with the server. + * This session is established during the initialization process and is used for + * sending requests and notifications. + * @return The MCP client session + */ + McpClientSession mcpSession(); + + /** + * Returns the result of the MCP initialization process. This result contains + * information about the protocol version, capabilities, server info, and + * instructions provided by the server during the initialization phase. + * @return The result of the MCP initialization process + */ + McpSchema.InitializeResult initializeResult(); + + } + + /** + * Default implementation of the {@link Initialization} interface that manages the MCP + * client initialization process. + */ + private static class DefaultInitialization implements Initialization { + + /** + * A sink that emits the result of the MCP initialization process. It allows + * subscribers to wait for the initialization to complete. + */ + private final Sinks.One initSink; + + /** + * Holds the result of the MCP initialization process. It is used to cache the + * result for future requests. + */ + private final AtomicReference result; + + /** + * Holds the MCP client session that is used to communicate with the server. It is + * set during the initialization process and used for sending requests and + * notifications. + */ + private final AtomicReference mcpClientSession; + + private DefaultInitialization() { + this.initSink = Sinks.one(); + this.result = new AtomicReference<>(); + this.mcpClientSession = new AtomicReference<>(); + } + + // --------------------------------------------------- + // Public access for mcpSession and initializeResult because they are + // used in by the McpAsyncClient. + // ---------------------------------------------------- + public McpClientSession mcpSession() { + return this.mcpClientSession.get(); + } + + public McpSchema.InitializeResult initializeResult() { + return this.result.get(); + } + + // --------------------------------------------------- + // Private accessors used internally by the LifecycleInitializer to set the MCP + // client session and complete the initialization process. + // --------------------------------------------------- + private void setMcpClientSession(McpClientSession mcpClientSession) { + this.mcpClientSession.set(mcpClientSession); + } + + /** + * Returns a Mono that completes when the MCP client initialization is complete. + * This allows subscribers to wait for the initialization to finish before + * proceeding with further operations. + * @return A Mono that emits the result of the MCP initialization process + */ + private Mono await() { + return this.initSink.asMono(); + } + + /** + * Completes the initialization process with the given result. It caches the + * result and emits it to all subscribers waiting for the initialization to + * complete. + * @param initializeResult The result of the MCP initialization process + */ + private void complete(McpSchema.InitializeResult initializeResult) { + // first ensure the result is cached + this.result.set(initializeResult); + // inform all the subscribers waiting for the initialization + this.initSink.emitValue(initializeResult, Sinks.EmitFailureHandler.FAIL_FAST); + } + + private void error(Throwable t) { + this.initSink.emitError(t, Sinks.EmitFailureHandler.FAIL_FAST); + } + + private void close() { + this.mcpSession().close(); + } + + private Mono closeGracefully() { + return this.mcpSession().closeGracefully(); + } + + } + + public boolean isInitialized() { + return this.currentInitializationResult() != null; + } + + public McpSchema.InitializeResult currentInitializationResult() { + DefaultInitialization current = this.initializationRef.get(); + McpSchema.InitializeResult initializeResult = current != null ? current.result.get() : null; + return initializeResult; + } + + /** + * Hook to handle exceptions that occur during the MCP transport session. + *

+ * If the exception is a {@link McpTransportSessionNotFoundException}, it indicates + * that the session was not found, and we should re-initialize the client. + *

+ * @param t The exception to handle + */ + public void handleException(Throwable t) { + logger.warn("Handling exception", t); + if (t instanceof McpTransportSessionNotFoundException) { + DefaultInitialization previous = this.initializationRef.getAndSet(null); + if (previous != null) { + previous.close(); + } + // Providing an empty operation since we are only interested in triggering + // the implicit initialization step. + withIntitialization("re-initializing", result -> Mono.empty()).subscribe(); + } + } + + /** + * Utility method to ensure the initialization is established before executing an + * operation. + * @param The type of the result Mono + * @param actionName The action to perform when the client is initialized + * @param operation The operation to execute when the client is initialized + * @return A Mono that completes with the result of the operation + */ + public Mono withIntitialization(String actionName, Function> operation) { + return Mono.deferContextual(ctx -> { + DefaultInitialization newInit = new DefaultInitialization(); + DefaultInitialization previous = this.initializationRef.compareAndExchange(null, newInit); + + boolean needsToInitialize = previous == null; + logger.debug(needsToInitialize ? "Initialization process started" : "Joining previous initialization"); + + Mono initializationJob = needsToInitialize ? doInitialize(newInit, ctx) + : previous.await(); + + return initializationJob.map(initializeResult -> this.initializationRef.get()) + .timeout(this.initializationTimeout) + .onErrorResume(ex -> { + logger.warn("Failed to initialize", ex); + return Mono.error(new McpError("Client failed to initialize " + actionName)); + }) + .flatMap(operation); + }); + } + + private Mono doInitialize(DefaultInitialization initialization, ContextView ctx) { + initialization.setMcpClientSession(this.sessionSupplier.apply(ctx)); + + McpClientSession mcpClientSession = initialization.mcpSession(); + + String latestVersion = this.protocolVersions.get(this.protocolVersions.size() - 1); + + McpSchema.InitializeRequest initializeRequest = new McpSchema.InitializeRequest(latestVersion, + this.clientCapabilities, this.clientInfo); + + Mono result = mcpClientSession.sendRequest(McpSchema.METHOD_INITIALIZE, + initializeRequest, McpAsyncClient.INITIALIZE_RESULT_TYPE_REF); + + return result.flatMap(initializeResult -> { + logger.info("Server response with Protocol: {}, Capabilities: {}, Info: {} and Instructions {}", + initializeResult.protocolVersion(), initializeResult.capabilities(), initializeResult.serverInfo(), + initializeResult.instructions()); + + if (!this.protocolVersions.contains(initializeResult.protocolVersion())) { + return Mono.error(new McpError( + "Unsupported protocol version from the server: " + initializeResult.protocolVersion())); + } + + return mcpClientSession.sendNotification(McpSchema.METHOD_NOTIFICATION_INITIALIZED, null) + .thenReturn(initializeResult); + }).doOnNext(initialization::complete).onErrorResume(ex -> { + initialization.error(ex); + return Mono.error(ex); + }); + } + + /** + * Closes the current initialization if it exists. + */ + public void close() { + DefaultInitialization current = this.initializationRef.getAndSet(null); + if (current != null) { + current.close(); + } + } + + /** + * Gracefully closes the current initialization if it exists. + * @return A Mono that completes when the connection is closed + */ + public Mono closeGracefully() { + return Mono.defer(() -> { + DefaultInitialization current = this.initializationRef.getAndSet(null); + Mono sessionClose = current != null ? current.closeGracefully() : Mono.empty(); + return sessionClose; + }); + } + +} \ No newline at end of file diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java index fa76f3977..cf8142c68 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java +++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java @@ -10,7 +10,6 @@ import java.util.List; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicReference; import java.util.function.Function; import org.slf4j.Logger; @@ -19,8 +18,6 @@ import com.fasterxml.jackson.core.type.TypeReference; import io.modelcontextprotocol.spec.McpClientSession; -import io.modelcontextprotocol.spec.McpClientSession.NotificationHandler; -import io.modelcontextprotocol.spec.McpClientSession.RequestHandler; import io.modelcontextprotocol.spec.McpClientTransport; import io.modelcontextprotocol.spec.McpError; import io.modelcontextprotocol.spec.McpSchema; @@ -36,13 +33,12 @@ import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification; import io.modelcontextprotocol.spec.McpSchema.PaginatedRequest; import io.modelcontextprotocol.spec.McpSchema.Root; -import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException; +import io.modelcontextprotocol.spec.McpClientSession.NotificationHandler; +import io.modelcontextprotocol.spec.McpClientSession.RequestHandler; import io.modelcontextprotocol.util.Assert; import io.modelcontextprotocol.util.Utils; import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; -import reactor.core.publisher.Sinks; -import reactor.util.context.ContextView; /** * The Model Context Protocol (MCP) client implementation that provides asynchronous @@ -104,13 +100,6 @@ public class McpAsyncClient { public static final TypeReference LOGGING_MESSAGE_NOTIFICATION_TYPE_REF = new TypeReference<>() { }; - private final AtomicReference initializationRef = new AtomicReference<>(); - - /** - * The max timeout to await for the client-server connection to be initialized. - */ - private final Duration initializationTimeout; - /** * Client capabilities. */ @@ -154,15 +143,9 @@ public class McpAsyncClient { private final McpClientTransport transport; /** - * Supported protocol versions. + * The lifecycle initializer that manages the client-server connection initialization. */ - private List protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION); - - /** - * The MCP session supplier that manages bidirectional JSON-RPC communication between - * clients and servers. - */ - private final Function sessionSupplier; + private final LifecycleInitializer initializer; /** * Create a new McpAsyncClient with the given transport and session request-response @@ -183,7 +166,6 @@ public class McpAsyncClient { this.clientCapabilities = features.clientCapabilities(); this.transport = transport; this.roots = new ConcurrentHashMap<>(features.roots()); - this.initializationTimeout = initializationTimeout; // Request Handlers Map> requestHandlers = new HashMap<>(); @@ -271,28 +253,11 @@ public class McpAsyncClient { notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_MESSAGE, asyncLoggingNotificationHandler(loggingConsumersFinal)); - this.transport.setExceptionHandler(this::handleException); - this.sessionSupplier = ctx -> new McpClientSession(requestTimeout, transport, requestHandlers, - notificationHandlers, con -> con.contextWrite(ctx)); - } - - private void handleException(Throwable t) { - logger.warn("Handling exception", t); - if (t instanceof McpTransportSessionNotFoundException) { - Initialization previous = this.initializationRef.getAndSet(null); - if (previous != null) { - previous.close(); - } - // Providing an empty operation since we are only interested in triggering the - // implicit initialization step. - withSession("re-initializing", result -> Mono.empty()).subscribe(); - } - } - - private McpSchema.InitializeResult currentInitializationResult() { - Initialization current = this.initializationRef.get(); - McpSchema.InitializeResult initializeResult = current != null ? current.result.get() : null; - return initializeResult; + this.initializer = new LifecycleInitializer(clientCapabilities, clientInfo, + List.of(McpSchema.LATEST_PROTOCOL_VERSION), initializationTimeout, + ctx -> new McpClientSession(requestTimeout, transport, requestHandlers, notificationHandlers, + con -> con.contextWrite(ctx))); + this.transport.setExceptionHandler(this.initializer::handleException); } /** @@ -300,7 +265,7 @@ private McpSchema.InitializeResult currentInitializationResult() { * @return The server capabilities */ public McpSchema.ServerCapabilities getServerCapabilities() { - McpSchema.InitializeResult initializeResult = currentInitializationResult(); + McpSchema.InitializeResult initializeResult = this.initializer.currentInitializationResult(); return initializeResult != null ? initializeResult.capabilities() : null; } @@ -310,7 +275,7 @@ public McpSchema.ServerCapabilities getServerCapabilities() { * @return The server instructions */ public String getServerInstructions() { - McpSchema.InitializeResult initializeResult = currentInitializationResult(); + McpSchema.InitializeResult initializeResult = this.initializer.currentInitializationResult(); return initializeResult != null ? initializeResult.instructions() : null; } @@ -319,7 +284,7 @@ public String getServerInstructions() { * @return The server implementation details */ public McpSchema.Implementation getServerInfo() { - McpSchema.InitializeResult initializeResult = currentInitializationResult(); + McpSchema.InitializeResult initializeResult = this.initializer.currentInitializationResult(); return initializeResult != null ? initializeResult.serverInfo() : null; } @@ -328,8 +293,7 @@ public McpSchema.Implementation getServerInfo() { * @return true if the client-server connection is initialized */ public boolean isInitialized() { - Initialization current = this.initializationRef.get(); - return current != null && (current.result.get() != null); + return this.initializer.isInitialized(); } /** @@ -352,10 +316,7 @@ public McpSchema.Implementation getClientInfo() { * Closes the client connection immediately. */ public void close() { - Initialization current = this.initializationRef.getAndSet(null); - if (current != null) { - current.close(); - } + this.initializer.close(); this.transport.close(); } @@ -365,9 +326,7 @@ public void close() { */ public Mono closeGracefully() { return Mono.defer(() -> { - Initialization current = this.initializationRef.getAndSet(null); - Mono sessionClose = current != null ? current.closeGracefully() : Mono.empty(); - return sessionClose.then(transport.closeGracefully()); + return this.initializer.closeGracefully().then(transport.closeGracefully()); }); } @@ -401,118 +360,7 @@ public Mono closeGracefully() { *

*/ public Mono initialize() { - return withSession("by explicit API call", init -> Mono.just(init.get())); - } - - private Mono doInitialize(Initialization initialization, ContextView ctx) { - initialization.setMcpClientSession(this.sessionSupplier.apply(ctx)); - - McpClientSession mcpClientSession = initialization.mcpSession(); - - String latestVersion = this.protocolVersions.get(this.protocolVersions.size() - 1); - - McpSchema.InitializeRequest initializeRequest = new McpSchema.InitializeRequest(// @formatter:off - latestVersion, - this.clientCapabilities, - this.clientInfo); // @formatter:on - - Mono result = mcpClientSession.sendRequest(McpSchema.METHOD_INITIALIZE, - initializeRequest, INITIALIZE_RESULT_TYPE_REF); - - return result.flatMap(initializeResult -> { - logger.info("Server response with Protocol: {}, Capabilities: {}, Info: {} and Instructions {}", - initializeResult.protocolVersion(), initializeResult.capabilities(), initializeResult.serverInfo(), - initializeResult.instructions()); - - if (!this.protocolVersions.contains(initializeResult.protocolVersion())) { - return Mono.error(new McpError( - "Unsupported protocol version from the server: " + initializeResult.protocolVersion())); - } - - return mcpClientSession.sendNotification(McpSchema.METHOD_NOTIFICATION_INITIALIZED, null) - .thenReturn(initializeResult); - }).doOnNext(initialization::complete).onErrorResume(ex -> { - initialization.error(ex); - return Mono.error(ex); - }); - } - - private static class Initialization { - - private final Sinks.One initSink = Sinks.one(); - - private final AtomicReference result = new AtomicReference<>(); - - private final AtomicReference mcpClientSession = new AtomicReference<>(); - - static Initialization create() { - return new Initialization(); - } - - void setMcpClientSession(McpClientSession mcpClientSession) { - this.mcpClientSession.set(mcpClientSession); - } - - McpClientSession mcpSession() { - return this.mcpClientSession.get(); - } - - McpSchema.InitializeResult get() { - return this.result.get(); - } - - Mono await() { - return this.initSink.asMono(); - } - - void complete(McpSchema.InitializeResult initializeResult) { - // first ensure the result is cached - this.result.set(initializeResult); - // inform all the subscribers waiting for the initialization - this.initSink.emitValue(initializeResult, Sinks.EmitFailureHandler.FAIL_FAST); - } - - void error(Throwable t) { - this.initSink.emitError(t, Sinks.EmitFailureHandler.FAIL_FAST); - } - - void close() { - this.mcpSession().close(); - } - - Mono closeGracefully() { - return this.mcpSession().closeGracefully(); - } - - } - - /** - * Utility method to handle the common pattern of ensuring initialization before - * executing an operation. - * @param The type of the result Mono - * @param actionName The action to perform when the client is initialized - * @param operation The operation to execute when the client is initialized - * @return A Mono that completes with the result of the operation - */ - private Mono withSession(String actionName, Function> operation) { - return Mono.deferContextual(ctx -> { - Initialization newInit = Initialization.create(); - Initialization previous = this.initializationRef.compareAndExchange(null, newInit); - - boolean needsToInitialize = previous == null; - logger.debug(needsToInitialize ? "Initialization process started" : "Joining previous initialization"); - - Mono initializationJob = needsToInitialize ? doInitialize(newInit, ctx) - : previous.await(); - - return initializationJob.map(initializeResult -> this.initializationRef.get()) - .timeout(this.initializationTimeout) - .onErrorResume(ex -> { - logger.warn("Failed to initialize", ex); - return Mono.error(new McpError("Client failed to initialize " + actionName)); - }) - .flatMap(operation); - }); + return this.initializer.withIntitialization("by explicit API call", init -> Mono.just(init.initializeResult())); } // -------------------------- @@ -524,7 +372,7 @@ private Mono withSession(String actionName, Function ping() { - return this.withSession("pinging the server", + return this.initializer.withIntitialization("pinging the server", init -> init.mcpSession().sendRequest(McpSchema.METHOD_PING, null, OBJECT_TYPE_REF)); } @@ -605,7 +453,7 @@ public Mono removeRoot(String rootUri) { * @return A Mono that completes when the notification is sent. */ public Mono rootsListChangedNotification() { - return this.withSession("sending roots list changed notification", + return this.initializer.withIntitialization("sending roots list changed notification", init -> init.mcpSession().sendNotification(McpSchema.METHOD_NOTIFICATION_ROOTS_LIST_CHANGED)); } @@ -664,8 +512,8 @@ private RequestHandler elicitationCreateHandler() { * @see #listTools() */ public Mono callTool(McpSchema.CallToolRequest callToolRequest) { - return this.withSession("calling tools", init -> { - if (init.get().capabilities().tools() == null) { + return this.initializer.withIntitialization("calling tools", init -> { + if (init.initializeResult().capabilities().tools() == null) { return Mono.error(new McpError("Server does not provide tools capability")); } return init.mcpSession() @@ -693,8 +541,8 @@ public Mono listTools() { * @return A Mono that emits the list of tools result */ public Mono listTools(String cursor) { - return this.withSession("listing tools", init -> { - if (init.get().capabilities().tools() == null) { + return this.initializer.withIntitialization("listing tools", init -> { + if (init.initializeResult().capabilities().tools() == null) { return Mono.error(new McpError("Server does not provide tools capability")); } return init.mcpSession() @@ -757,8 +605,8 @@ public Mono listResources() { * @see #readResource(McpSchema.Resource) */ public Mono listResources(String cursor) { - return this.withSession("listing resources", init -> { - if (init.get().capabilities().resources() == null) { + return this.initializer.withIntitialization("listing resources", init -> { + if (init.initializeResult().capabilities().resources() == null) { return Mono.error(new McpError("Server does not provide the resources capability")); } return init.mcpSession() @@ -789,8 +637,8 @@ public Mono readResource(McpSchema.Resource resour * @see McpSchema.ReadResourceResult */ public Mono readResource(McpSchema.ReadResourceRequest readResourceRequest) { - return this.withSession("reading resources", init -> { - if (init.get().capabilities().resources() == null) { + return this.initializer.withIntitialization("reading resources", init -> { + if (init.initializeResult().capabilities().resources() == null) { return Mono.error(new McpError("Server does not provide the resources capability")); } return init.mcpSession() @@ -827,8 +675,8 @@ public Mono listResourceTemplates() { * @see McpSchema.ListResourceTemplatesResult */ public Mono listResourceTemplates(String cursor) { - return this.withSession("listing resource templates", init -> { - if (init.get().capabilities().resources() == null) { + return this.initializer.withIntitialization("listing resource templates", init -> { + if (init.initializeResult().capabilities().resources() == null) { return Mono.error(new McpError("Server does not provide the resources capability")); } return init.mcpSession() @@ -847,7 +695,7 @@ public Mono listResourceTemplates(String * @see #unsubscribeResource(McpSchema.UnsubscribeRequest) */ public Mono subscribeResource(McpSchema.SubscribeRequest subscribeRequest) { - return this.withSession("subscribing to resources", init -> init.mcpSession() + return this.initializer.withIntitialization("subscribing to resources", init -> init.mcpSession() .sendRequest(McpSchema.METHOD_RESOURCES_SUBSCRIBE, subscribeRequest, VOID_TYPE_REFERENCE)); } @@ -861,7 +709,7 @@ public Mono subscribeResource(McpSchema.SubscribeRequest subscribeRequest) * @see #subscribeResource(McpSchema.SubscribeRequest) */ public Mono unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest) { - return this.withSession("unsubscribing from resources", init -> init.mcpSession() + return this.initializer.withIntitialization("unsubscribing from resources", init -> init.mcpSession() .sendRequest(McpSchema.METHOD_RESOURCES_UNSUBSCRIBE, unsubscribeRequest, VOID_TYPE_REFERENCE)); } @@ -927,7 +775,7 @@ public Mono listPrompts() { * @see #getPrompt(GetPromptRequest) */ public Mono listPrompts(String cursor) { - return this.withSession("listing prompts", init -> init.mcpSession() + return this.initializer.withIntitialization("listing prompts", init -> init.mcpSession() .sendRequest(McpSchema.METHOD_PROMPT_LIST, new PaginatedRequest(cursor), LIST_PROMPTS_RESULT_TYPE_REF)); } @@ -941,7 +789,7 @@ public Mono listPrompts(String cursor) { * @see #listPrompts() */ public Mono getPrompt(GetPromptRequest getPromptRequest) { - return this.withSession("getting prompts", init -> init.mcpSession() + return this.initializer.withIntitialization("getting prompts", init -> init.mcpSession() .sendRequest(McpSchema.METHOD_PROMPT_GET, getPromptRequest, GET_PROMPT_RESULT_TYPE_REF)); } @@ -992,7 +840,7 @@ public Mono setLoggingLevel(LoggingLevel loggingLevel) { return Mono.error(new McpError("Logging level must not be null")); } - return this.withSession("setting logging level", init -> { + return this.initializer.withIntitialization("setting logging level", init -> { var params = new McpSchema.SetLevelRequest(loggingLevel); return init.mcpSession().sendRequest(McpSchema.METHOD_LOGGING_SET_LEVEL, params, OBJECT_TYPE_REF).then(); }); @@ -1004,7 +852,7 @@ public Mono setLoggingLevel(LoggingLevel loggingLevel) { * @param protocolVersions the Client supported protocol versions. */ void setProtocolVersions(List protocolVersions) { - this.protocolVersions = protocolVersions; + this.initializer.setProtocolVersions(protocolVersions); } // -------------------------- @@ -1024,7 +872,7 @@ void setProtocolVersions(List protocolVersions) { * @see McpSchema.CompleteResult */ public Mono completeCompletion(McpSchema.CompleteRequest completeRequest) { - return this.withSession("complete completions", init -> init.mcpSession() + return this.initializer.withIntitialization("complete completions", init -> init.mcpSession() .sendRequest(McpSchema.METHOD_COMPLETION_COMPLETE, completeRequest, COMPLETION_COMPLETE_RESULT_TYPE_REF)); } diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java new file mode 100644 index 000000000..c8d691924 --- /dev/null +++ b/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java @@ -0,0 +1,412 @@ +/* + * Copyright 2024-2024 the original author or authors. + */ + +package io.modelcontextprotocol.client; + +import java.time.Duration; +import java.util.List; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.Function; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.mockito.Mock; +import org.mockito.MockitoAnnotations; + +import io.modelcontextprotocol.spec.McpClientSession; +import io.modelcontextprotocol.spec.McpError; +import io.modelcontextprotocol.spec.McpSchema; +import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException; +import reactor.core.publisher.Mono; +import reactor.core.scheduler.Schedulers; +import reactor.test.StepVerifier; +import reactor.test.scheduler.VirtualTimeScheduler; +import reactor.util.context.Context; +import reactor.util.context.ContextView; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.times; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Tests for {@link LifecycleInitializer}. + */ +class LifecycleInitializerTests { + + private static final Duration INITIALIZATION_TIMEOUT = Duration.ofSeconds(5); + + private static final McpSchema.ClientCapabilities CLIENT_CAPABILITIES = McpSchema.ClientCapabilities.builder() + .build(); + + private static final McpSchema.Implementation CLIENT_INFO = new McpSchema.Implementation("test-client", "1.0.0"); + + private static final List PROTOCOL_VERSIONS = List.of("1.0.0", "2.0.0"); + + private static final McpSchema.InitializeResult MOCK_INIT_RESULT = new McpSchema.InitializeResult("2.0.0", + McpSchema.ServerCapabilities.builder().build(), new McpSchema.Implementation("test-server", "1.0.0"), + "Test instructions"); + + @Mock + private McpClientSession mockClientSession; + + @Mock + private Function mockSessionSupplier; + + private LifecycleInitializer initializer; + + @BeforeEach + void setUp() { + MockitoAnnotations.openMocks(this); + + when(mockSessionSupplier.apply(any(ContextView.class))).thenReturn(mockClientSession); + when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any())) + .thenReturn(Mono.just(MOCK_INIT_RESULT)); + when(mockClientSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any())) + .thenReturn(Mono.empty()); + when(mockClientSession.closeGracefully()).thenReturn(Mono.empty()); + + initializer = new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, PROTOCOL_VERSIONS, + INITIALIZATION_TIMEOUT, mockSessionSupplier); + } + + @Test + void constructorShouldValidateParameters() { + assertThatThrownBy(() -> new LifecycleInitializer(null, CLIENT_INFO, PROTOCOL_VERSIONS, INITIALIZATION_TIMEOUT, + mockSessionSupplier)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Client capabilities must not be null"); + + assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, null, PROTOCOL_VERSIONS, + INITIALIZATION_TIMEOUT, mockSessionSupplier)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Client info must not be null"); + + assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, null, + INITIALIZATION_TIMEOUT, mockSessionSupplier)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Protocol versions must not be empty"); + + assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, List.of(), + INITIALIZATION_TIMEOUT, mockSessionSupplier)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Protocol versions must not be empty"); + + assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, PROTOCOL_VERSIONS, null, + mockSessionSupplier)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Initialization timeout must not be null"); + + assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, PROTOCOL_VERSIONS, + INITIALIZATION_TIMEOUT, null)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Session supplier must not be null"); + } + + @Test + void shouldInitializeSuccessfully() { + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .assertNext(result -> { + assertThat(result).isEqualTo(MOCK_INIT_RESULT); + assertThat(initializer.isInitialized()).isTrue(); + assertThat(initializer.currentInitializationResult()).isEqualTo(MOCK_INIT_RESULT); + }) + .verifyComplete(); + + verify(mockClientSession).sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(McpSchema.InitializeRequest.class), + any()); + verify(mockClientSession).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), eq(null)); + } + + @Test + void shouldUseLatestProtocolVersionInInitializeRequest() { + AtomicReference capturedRequest = new AtomicReference<>(); + + when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any())).thenAnswer(invocation -> { + capturedRequest.set((McpSchema.InitializeRequest) invocation.getArgument(1)); + return Mono.just(MOCK_INIT_RESULT); + }); + + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .assertNext(result -> { + assertThat(capturedRequest.get().protocolVersion()).isEqualTo("2.0.0"); // Latest + // version + assertThat(capturedRequest.get().capabilities()).isEqualTo(CLIENT_CAPABILITIES); + assertThat(capturedRequest.get().clientInfo()).isEqualTo(CLIENT_INFO); + }) + .verifyComplete(); + } + + @Test + void shouldFailForUnsupportedProtocolVersion() { + McpSchema.InitializeResult unsupportedResult = new McpSchema.InitializeResult("999.0.0", // Unsupported + // version + McpSchema.ServerCapabilities.builder().build(), new McpSchema.Implementation("test-server", "1.0.0"), + "Test instructions"); + + when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any())) + .thenReturn(Mono.just(unsupportedResult)); + + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .expectError(McpError.class) + .verify(); + + verify(mockClientSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any()); + } + + @Test + void shouldTimeoutOnSlowInitialization() { + VirtualTimeScheduler virtualTimeScheduler = VirtualTimeScheduler.getOrSet(); + + Duration INITIALIZE_TIMEOUT = Duration.ofSeconds(1); + Duration SLOW_RESPONSE_DELAY = Duration.ofSeconds(5); + + LifecycleInitializer shortTimeoutInitializer = new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, + PROTOCOL_VERSIONS, INITIALIZE_TIMEOUT, mockSessionSupplier); + + when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any())) + .thenReturn(Mono.just(MOCK_INIT_RESULT).delayElement(SLOW_RESPONSE_DELAY, virtualTimeScheduler)); + + StepVerifier + .withVirtualTime(() -> shortTimeoutInitializer.withIntitialization("test", + init -> Mono.just(init.initializeResult())), () -> virtualTimeScheduler, Long.MAX_VALUE) + .expectSubscription() + .expectNoEvent(INITIALIZE_TIMEOUT) + .expectError(McpError.class) + .verify(); + } + + @Test + void shouldReuseExistingInitialization() { + // First initialization + StepVerifier.create(initializer.withIntitialization("test1", init -> Mono.just("result1"))) + .expectNext("result1") + .verifyComplete(); + + // Second call should reuse the same initialization + StepVerifier.create(initializer.withIntitialization("test2", init -> Mono.just("result2"))) + .expectNext("result2") + .verifyComplete(); + + // Verify session was created only once + verify(mockSessionSupplier, times(1)).apply(any(ContextView.class)); + verify(mockClientSession, times(1)).sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()); + } + + @Test + void shouldHandleConcurrentInitializationRequests() { + AtomicInteger sessionCreationCount = new AtomicInteger(0); + + when(mockSessionSupplier.apply(any(ContextView.class))).thenAnswer(invocation -> { + sessionCreationCount.incrementAndGet(); + return mockClientSession; + }); + + // Start multiple concurrent initializations using subscribeOn with parallel + // scheduler + Mono init1 = initializer.withIntitialization("test1", init -> Mono.just("result1")) + .subscribeOn(Schedulers.parallel()); + Mono init2 = initializer.withIntitialization("test2", init -> Mono.just("result2")) + .subscribeOn(Schedulers.parallel()); + Mono init3 = initializer.withIntitialization("test3", init -> Mono.just("result3")) + .subscribeOn(Schedulers.parallel()); + + StepVerifier.create(Mono.zip(init1, init2, init3)).assertNext(tuple -> { + assertThat(tuple.getT1()).isEqualTo("result1"); + assertThat(tuple.getT2()).isEqualTo("result2"); + assertThat(tuple.getT3()).isEqualTo("result3"); + }).verifyComplete(); + + // Should only create one session despite concurrent requests + assertThat(sessionCreationCount.get()).isEqualTo(1); + verify(mockClientSession, times(1)).sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()); + } + + @Test + void shouldHandleInitializationFailure() { + when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any())) + .thenReturn(Mono.error(new RuntimeException("Connection failed"))); + + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .expectError(McpError.class) + .verify(); + + assertThat(initializer.isInitialized()).isFalse(); + assertThat(initializer.currentInitializationResult()).isNull(); + } + + @Test + void shouldHandleTransportSessionNotFoundException() { + // successful initialization first + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .expectNext(MOCK_INIT_RESULT) + .verifyComplete(); + + assertThat(initializer.isInitialized()).isTrue(); + + // Simulate transport session not found + initializer.handleException(new McpTransportSessionNotFoundException("Session not found")); + + assertThat(initializer.isInitialized()).isTrue(); + + // Verify that the session was closed and re-initialized + verify(mockClientSession).close(); + + // Verify session was created 2 times (once for initial and once for + // re-initialization) + verify(mockSessionSupplier, times(2)).apply(any(ContextView.class)); + } + + @Test + void shouldHandleOtherExceptions() { + // Simulate a successful initialization first + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .expectNext(MOCK_INIT_RESULT) + .verifyComplete(); + + assertThat(initializer.isInitialized()).isTrue(); + + // Simulate other exception (should not trigger re-initialization) + initializer.handleException(new RuntimeException("Some other error")); + + // Should still be initialized + assertThat(initializer.isInitialized()).isTrue(); + verify(mockClientSession, never()).close(); + // Verify that the session was not re-created + verify(mockSessionSupplier, times(1)).apply(any(ContextView.class)); + } + + @Test + void shouldCloseGracefully() { + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .expectNext(MOCK_INIT_RESULT) + .verifyComplete(); + + StepVerifier.create(initializer.closeGracefully()).verifyComplete(); + + verify(mockClientSession).closeGracefully(); + assertThat(initializer.isInitialized()).isFalse(); + } + + @Test + void shouldCloseImmediately() { + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .expectNext(MOCK_INIT_RESULT) + .verifyComplete(); + + // Close immediately + initializer.close(); + + verify(mockClientSession).close(); + assertThat(initializer.isInitialized()).isFalse(); + } + + @Test + void shouldHandleCloseWithoutInitialization() { + // Close without initialization should not throw + initializer.close(); + + StepVerifier.create(initializer.closeGracefully()).verifyComplete(); + + verify(mockClientSession, never()).close(); + verify(mockClientSession, never()).closeGracefully(); + } + + @Test + void shouldSetProtocolVersionsForTesting() { + List newVersions = List.of("3.0.0", "4.0.0"); + initializer.setProtocolVersions(newVersions); + + AtomicReference capturedRequest = new AtomicReference<>(); + + when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any())).thenAnswer(invocation -> { + capturedRequest.set((McpSchema.InitializeRequest) invocation.getArgument(1)); + return Mono.just(new McpSchema.InitializeResult("4.0.0", McpSchema.ServerCapabilities.builder().build(), + new McpSchema.Implementation("test-server", "1.0.0"), "Test instructions")); + }); + + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .assertNext(result -> { + // Latest from new versions + assertThat(capturedRequest.get().protocolVersion()).isEqualTo("4.0.0"); + }) + .verifyComplete(); + } + + @Test + void shouldPassContextToSessionSupplier() { + String contextKey = "test.key"; + String contextValue = "test.value"; + + AtomicReference capturedContext = new AtomicReference<>(); + + when(mockSessionSupplier.apply(any(ContextView.class))).thenAnswer(invocation -> { + capturedContext.set(invocation.getArgument(0)); + return mockClientSession; + }); + + StepVerifier + .create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())) + .contextWrite(Context.of(contextKey, contextValue))) + .expectNext(MOCK_INIT_RESULT) + .verifyComplete(); + + assertThat(capturedContext.get().hasKey(contextKey)).isTrue(); + assertThat((String) capturedContext.get().get(contextKey)).isEqualTo(contextValue); + } + + @Test + void shouldProvideAccessToMcpSessionAndInitializeResult() { + StepVerifier.create(initializer.withIntitialization("test", init -> { + assertThat(init.mcpSession()).isEqualTo(mockClientSession); + assertThat(init.initializeResult()).isEqualTo(MOCK_INIT_RESULT); + return Mono.just("success"); + })).expectNext("success").verifyComplete(); + } + + @Test + void shouldHandleNotificationFailure() { + when(mockClientSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any())) + .thenReturn(Mono.error(new RuntimeException("Notification failed"))); + + StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))) + .expectError(RuntimeException.class) + .verify(); + + verify(mockClientSession).sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()); + verify(mockClientSession).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), eq(null)); + } + + @Test + void shouldReturnNullWhenNotInitialized() { + assertThat(initializer.isInitialized()).isFalse(); + assertThat(initializer.currentInitializationResult()).isNull(); + } + + @Test + void shouldReinitializeAfterTransportSessionException() { + // First initialization + StepVerifier.create(initializer.withIntitialization("test1", init -> Mono.just("result1"))) + .expectNext("result1") + .verifyComplete(); + + // Simulate transport session exception + initializer.handleException(new McpTransportSessionNotFoundException("Session lost")); + + // Should be able to initialize again + StepVerifier.create(initializer.withIntitialization("test2", init -> Mono.just("result2"))) + .expectNext("result2") + .verifyComplete(); + + // Verify two separate initializations occurred + verify(mockSessionSupplier, times(2)).apply(any(ContextView.class)); + verify(mockClientSession, times(2)).sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()); + } + +} From 95df67ec0546c0721874ba9549ce5397889c3913 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dariusz=20J=C4=99drzejczyk?= Date: Fri, 4 Jul 2025 16:48:25 +0200 Subject: [PATCH 004/125] Fix non-OK HTTP POST responses handling (#374) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently, JDK HttpClient SSE implementation incorrectly handles a non-2xx HTTP response code for POST. Instead of immediately failing the caller, it ignores the issue and the user awaits until the timeout kicks in. Set HttpClient to use HTTP/1.1 version explicitly for tests A related problem happened with the WebClient Streamable HTTP implementation, where the error was swallowed for non-400 responses. Signed-off-by: Dariusz Jędrzejczyk --- .../WebClientStreamableHttpTransport.java | 2 +- .../server/WebMvcSseIntegrationTests.java | 30 +++++++++++++++++++ .../HttpClientSseClientTransport.java | 12 +++++--- .../HttpClientSseClientTransportTests.java | 4 ++- 4 files changed, 42 insertions(+), 6 deletions(-) diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java index e60451706..53b59cb30 100644 --- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java +++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java @@ -354,7 +354,7 @@ private Flux extractError(ClientResponse response, Str if (responseException.getStatusCode().isSameCodeAs(HttpStatus.BAD_REQUEST)) { return Mono.error(new McpTransportSessionNotFoundException(sessionRepresentation, toPropagate)); } - return Mono.empty(); + return Mono.error(toPropagate); }).flux(); } diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java index 43d6f40fe..b7a9e4a09 100644 --- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java +++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java @@ -32,6 +32,7 @@ import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import reactor.core.publisher.Mono; +import reactor.core.scheduler.Schedulers; import reactor.test.StepVerifier; import org.springframework.context.annotation.Bean; @@ -96,9 +97,11 @@ public void before() { @AfterEach public void after() { + reactor.netty.http.HttpResources.disposeLoopsAndConnections(); if (mcpServerTransportProvider != null) { mcpServerTransportProvider.closeGracefully().block(); } + Schedulers.shutdownNow(); if (tomcatServer.appContext() != null) { tomcatServer.appContext().close(); } @@ -779,6 +782,33 @@ void testToolCallSuccess() { mcpServer.close(); } + @Test + void testThrowingToolCallIsCaughtBeforeTimeout() { + McpSyncServer mcpServer = McpServer.sync(mcpServerTransportProvider) + .capabilities(ServerCapabilities.builder().tools(true).build()) + .tools(new McpServerFeatures.SyncToolSpecification( + new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + // We trigger a timeout on blocking read, raising an exception + Mono.never().block(Duration.ofSeconds(1)); + return null; + })) + .build(); + + try (var mcpClient = clientBuilder.requestTimeout(Duration.ofMillis(6666)).build()) { + InitializeResult initResult = mcpClient.initialize(); + assertThat(initResult).isNotNull(); + + // We expect the tool call to fail immediately with the exception raised by + // the offending tool + // instead of getting back a timeout. + assertThatExceptionOfType(McpError.class) + .isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()))) + .withMessageContaining("Timeout on blocking read"); + } + + mcpServer.close(); + } + @Test void testToolListChangeHandlingSuccess() { diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java index ab48fc0f7..271f38231 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java +++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java @@ -421,13 +421,17 @@ public Mono sendMessage(JSONRPCMessage message) { } return this.serializeMessage(message) - .flatMap(body -> sendHttpPost(messageEndpointUri, body)) - .doOnNext(response -> { + .flatMap(body -> sendHttpPost(messageEndpointUri, body).handle((response, sink) -> { if (response.statusCode() != 200 && response.statusCode() != 201 && response.statusCode() != 202 && response.statusCode() != 206) { - logger.error("Error sending message: {}", response.statusCode()); + sink.error(new RuntimeException( + "Sending message failed with a non-OK HTTP code: " + response.statusCode())); } - }) + else { + sink.next(response); + sink.complete(); + } + })) .doOnError(error -> { if (!isClosing) { logger.error("Error sending message: {}", error.getMessage()); diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java index e4348be25..3f1b71e63 100644 --- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java +++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java @@ -59,7 +59,9 @@ static class TestHttpClientSseClientTransport extends HttpClientSseClientTranspo private Sinks.Many> events = Sinks.many().unicast().onBackpressureBuffer(); public TestHttpClientSseClientTransport(final String baseUri) { - super(HttpClient.newHttpClient(), HttpRequest.newBuilder(), baseUri, "/sse", new ObjectMapper()); + super(HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build(), + HttpRequest.newBuilder().header("Content-Type", "application/json"), baseUri, "/sse", + new ObjectMapper()); } public int getInboundMessageCount() { From 901175e14ff2d2053238347c156766b61e1dd53c Mon Sep 17 00:00:00 2001 From: Christian Tzolov Date: Sun, 29 Jun 2025 07:38:38 +0200 Subject: [PATCH 005/125] refactor: deprecate tool spec's arguments-only handler in favor of CallToolRequest (#375) Tool handlers now receive CallToolRequest instead of raw arguments to enable access to additional metadata parameters like progressToken - Deprecate handlers that take only Map arguments - Introduce new handlers that receive the full CallToolRequest object - Maintain backward compatibility with deprecated call handlers - Enhance API to provide access to complete tool request context beyond just arguments - Add builder pattern for AsyncToolSpecification and SyncToolSpecification - Add duplicate tool name validation during server building and runtime registration - Update all test files to use new callTool handlers and builder pattern - Add test coverage for new builder functionality and CallToolRequest handling Signed-off-by: Christian Tzolov --- .../WebFluxSseIntegrationTests.java | 371 ++++++++------- .../server/WebMvcSseIntegrationTests.java | 374 ++++++++------- .../server/AbstractMcpAsyncServerTests.java | 100 +++- .../server/AbstractMcpSyncServerTests.java | 113 ++++- .../server/McpAsyncServer.java | 6 +- .../server/McpServer.java | 112 ++++- .../server/McpServerFeatures.java | 307 ++++++++---- .../server/McpSyncServer.java | 1 + .../server/AbstractMcpAsyncServerTests.java | 102 +++- .../server/AbstractMcpSyncServerTests.java | 111 ++++- .../AsyncToolSpecificationBuilderTest.java | 229 +++++++++ .../server/BaseMcpAsyncServerTests.java | 5 - .../SyncToolSpecificationBuilderTest.java | 98 ++++ ...rverTransportProviderIntegrationTests.java | 450 +++++++++--------- 14 files changed, 1687 insertions(+), 692 deletions(-) create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java delete mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/BaseMcpAsyncServerTests.java create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java index c2ad1d68e..4d123055d 100644 --- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java +++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java @@ -3,6 +3,12 @@ */ package io.modelcontextprotocol; +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatExceptionOfType; +import static org.assertj.core.api.Assertions.assertWith; +import static org.awaitility.Awaitility.await; +import static org.mockito.Mockito.mock; + import java.time.Duration; import java.util.List; import java.util.Map; @@ -15,39 +21,50 @@ import java.util.function.Function; import java.util.stream.Collectors; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; +import org.springframework.http.server.reactive.HttpHandler; +import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter; +import org.springframework.web.client.RestClient; +import org.springframework.web.reactive.function.client.WebClient; +import org.springframework.web.reactive.function.server.RouterFunctions; + import com.fasterxml.jackson.databind.ObjectMapper; + import io.modelcontextprotocol.client.McpClient; import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport; import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport; import io.modelcontextprotocol.server.McpServer; import io.modelcontextprotocol.server.McpServerFeatures; -import io.modelcontextprotocol.server.TestUtil; import io.modelcontextprotocol.server.McpSyncServerExchange; +import io.modelcontextprotocol.server.TestUtil; import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider; import io.modelcontextprotocol.spec.McpError; import io.modelcontextprotocol.spec.McpSchema; -import io.modelcontextprotocol.spec.McpSchema.*; -import org.junit.jupiter.api.AfterEach; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.ValueSource; +import io.modelcontextprotocol.spec.McpSchema.CallToolResult; +import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities; +import io.modelcontextprotocol.spec.McpSchema.CompleteRequest; +import io.modelcontextprotocol.spec.McpSchema.CompleteResult; +import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest; +import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult; +import io.modelcontextprotocol.spec.McpSchema.ElicitRequest; +import io.modelcontextprotocol.spec.McpSchema.ElicitResult; +import io.modelcontextprotocol.spec.McpSchema.InitializeResult; +import io.modelcontextprotocol.spec.McpSchema.ModelPreferences; +import io.modelcontextprotocol.spec.McpSchema.Prompt; +import io.modelcontextprotocol.spec.McpSchema.PromptArgument; +import io.modelcontextprotocol.spec.McpSchema.PromptReference; +import io.modelcontextprotocol.spec.McpSchema.Role; +import io.modelcontextprotocol.spec.McpSchema.Root; +import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities; +import io.modelcontextprotocol.spec.McpSchema.Tool; import reactor.core.publisher.Mono; import reactor.netty.DisposableServer; import reactor.netty.http.server.HttpServer; - -import org.springframework.http.server.reactive.HttpHandler; -import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter; -import org.springframework.web.client.RestClient; -import org.springframework.web.reactive.function.client.WebClient; -import org.springframework.web.reactive.function.server.RouterFunctions; import reactor.test.StepVerifier; -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatExceptionOfType; -import static org.assertj.core.api.Assertions.assertWith; -import static org.awaitility.Awaitility.await; -import static org.mockito.Mockito.mock; - class WebFluxSseIntegrationTests { private static final int PORT = TestUtil.findAvailablePort(); @@ -103,10 +120,11 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) { var clientBuilder = clientBuilders.get(clientType); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), - (exchange, request) -> exchange.createMessage(mock(CreateMessageRequest.class)) - .thenReturn(mock(CallToolResult.class))); + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> exchange.createMessage(mock(CreateMessageRequest.class)) + .thenReturn(mock(CallToolResult.class))) + .build(); var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build(); @@ -145,24 +163,26 @@ void testCreateMessageSuccess(String clientType) { AtomicReference samplingResult = new AtomicReference<>(); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - - var createMessageRequest = McpSchema.CreateMessageRequest.builder() - .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, - new McpSchema.TextContent("Test message")))) - .modelPreferences(ModelPreferences.builder() - .hints(List.of()) - .costPriority(1.0) - .speedPriority(1.0) - .intelligencePriority(1.0) - .build()) - .build(); - - return exchange.createMessage(createMessageRequest) - .doOnNext(samplingResult::set) - .thenReturn(callResponse); - }); + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + + var createMessageRequest = McpSchema.CreateMessageRequest.builder() + .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, + new McpSchema.TextContent("Test message")))) + .modelPreferences(ModelPreferences.builder() + .hints(List.of()) + .costPriority(1.0) + .speedPriority(1.0) + .intelligencePriority(1.0) + .build()) + .build(); + + return exchange.createMessage(createMessageRequest) + .doOnNext(samplingResult::set) + .thenReturn(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -221,24 +241,26 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr AtomicReference samplingResult = new AtomicReference<>(); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - - var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() - .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, - new McpSchema.TextContent("Test message")))) - .modelPreferences(ModelPreferences.builder() - .hints(List.of()) - .costPriority(1.0) - .speedPriority(1.0) - .intelligencePriority(1.0) - .build()) - .build(); - - return exchange.createMessage(craeteMessageRequest) - .doOnNext(samplingResult::set) - .thenReturn(callResponse); - }); + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + + var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() + .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, + new McpSchema.TextContent("Test message")))) + .modelPreferences(ModelPreferences.builder() + .hints(List.of()) + .costPriority(1.0) + .speedPriority(1.0) + .intelligencePriority(1.0) + .build()) + .build(); + + return exchange.createMessage(craeteMessageRequest) + .doOnNext(samplingResult::set) + .thenReturn(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .requestTimeout(Duration.ofSeconds(4)) @@ -297,16 +319,18 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() - .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, - new McpSchema.TextContent("Test message")))) - .build(); + var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() + .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, + new McpSchema.TextContent("Test message")))) + .build(); - return exchange.createMessage(craeteMessageRequest).thenReturn(callResponse); - }); + return exchange.createMessage(craeteMessageRequest).thenReturn(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .requestTimeout(Duration.ofSeconds(1)) @@ -340,13 +364,15 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) { var clientBuilder = clientBuilders.get(clientType); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - exchange.createElicitation(mock(ElicitRequest.class)).block(); + exchange.createElicitation(mock(ElicitRequest.class)).block(); - return Mono.just(mock(CallToolResult.class)); - }); + return Mono.just(mock(CallToolResult.class)); + }) + .build(); var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build(); @@ -383,23 +409,25 @@ void testCreateElicitationSuccess(String clientType) { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - var elicitationRequest = ElicitRequest.builder() - .message("Test message") - .requestedSchema( - Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) - .build(); + var elicitationRequest = ElicitRequest.builder() + .message("Test message") + .requestedSchema( + Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) + .build(); - StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT); - assertThat(result.content().get("message")).isEqualTo("Test message"); - }).verifyComplete(); + StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT); + assertThat(result.content().get("message")).isEqualTo("Test message"); + }).verifyComplete(); - return Mono.just(callResponse); - }); + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -445,23 +473,25 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - var elicitationRequest = ElicitRequest.builder() - .message("Test message") - .requestedSchema( - Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) - .build(); + var elicitationRequest = ElicitRequest.builder() + .message("Test message") + .requestedSchema( + Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) + .build(); - StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT); - assertThat(result.content().get("message")).isEqualTo("Test message"); - }).verifyComplete(); + StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT); + assertThat(result.content().get("message")).isEqualTo("Test message"); + }).verifyComplete(); - return Mono.just(callResponse); - }); + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -514,23 +544,25 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - var elicitationRequest = ElicitRequest.builder() - .message("Test message") - .requestedSchema( - Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) - .build(); + var elicitationRequest = ElicitRequest.builder() + .message("Test message") + .requestedSchema( + Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) + .build(); - StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT); - assertThat(result.content().get("message")).isEqualTo("Test message"); - }).verifyComplete(); + StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT); + assertThat(result.content().get("message")).isEqualTo("Test message"); + }).verifyComplete(); - return Mono.just(callResponse); - }); + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -605,13 +637,15 @@ void testRootsWithoutCapability(String clientType) { var clientBuilder = clientBuilders.get(clientType); - McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - exchange.listRoots(); // try to list roots + exchange.listRoots(); // try to list roots - return mock(CallToolResult.class); - }); + return mock(CallToolResult.class); + }) + .build(); var mcpServer = McpServer.sync(mcpServerTransportProvider).rootsChangeHandler((exchange, rootsUpdate) -> { }).tools(tool).build(); @@ -744,17 +778,19 @@ void testToolCallSuccess(String clientType) { var clientBuilder = clientBuilders.get(clientType); var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - // perform a blocking call to a remote service - String response = RestClient.create() - .get() - .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") - .retrieve() - .body(String.class); - assertThat(response).isNotBlank(); - return callResponse; - }); + McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + // perform a blocking call to a remote service + String response = RestClient.create() + .get() + .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") + .retrieve() + .body(String.class); + assertThat(response).isNotBlank(); + return callResponse; + }) + .build(); var mcpServer = McpServer.sync(mcpServerTransportProvider) .capabilities(ServerCapabilities.builder().tools(true).build()) @@ -784,17 +820,19 @@ void testToolListChangeHandlingSuccess(String clientType) { var clientBuilder = clientBuilders.get(clientType); var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - // perform a blocking call to a remote service - String response = RestClient.create() - .get() - .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") - .retrieve() - .body(String.class); - assertThat(response).isNotBlank(); - return callResponse; - }); + McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + // perform a blocking call to a remote service + String response = RestClient.create() + .get() + .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") + .retrieve() + .body(String.class); + assertThat(response).isNotBlank(); + return callResponse; + }) + .build(); AtomicReference> rootsRef = new AtomicReference<>(); @@ -835,9 +873,10 @@ void testToolListChangeHandlingSuccess(String clientType) { }); // Add a new tool - McpServerFeatures.SyncToolSpecification tool2 = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema), - (exchange, request) -> callResponse); + McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema)) + .callHandler((exchange, request) -> callResponse) + .build(); mcpServer.addTool(tool2); @@ -880,13 +919,13 @@ void testLoggingNotification(String clientType) throws InterruptedException { var clientBuilder = clientBuilders.get(clientType); // Create server with a tool that sends logging notifications - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema), - (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema)) + .callHandler((exchange, request) -> { - // Create and send notifications with different levels + // Create and send notifications with different levels - //@formatter:off + //@formatter:off return exchange // This should be filtered out (DEBUG < NOTICE) .loggingNotification(McpSchema.LoggingMessageNotification.builder() .level(McpSchema.LoggingLevel.DEBUG) @@ -919,7 +958,8 @@ void testLoggingNotification(String clientType) throws InterruptedException { .build())) .thenReturn(new CallToolResult("Logging test completed", false)); //@formatter:on - }); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -1035,26 +1075,27 @@ void testPingSuccess(String clientType) { // Create server with a tool that uses ping functionality AtomicReference executionOrder = new AtomicReference<>(""); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("ping-async-test", "Test ping async behavior", emptyJsonSchema), - (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("ping-async-test", "Test ping async behavior", emptyJsonSchema)) + .callHandler((exchange, request) -> { - executionOrder.set(executionOrder.get() + "1"); + executionOrder.set(executionOrder.get() + "1"); - // Test async ping behavior - return exchange.ping().doOnNext(result -> { + // Test async ping behavior + return exchange.ping().doOnNext(result -> { - assertThat(result).isNotNull(); - // Ping should return an empty object or map - assertThat(result).isInstanceOf(Map.class); + assertThat(result).isNotNull(); + // Ping should return an empty object or map + assertThat(result).isInstanceOf(Map.class); - executionOrder.set(executionOrder.get() + "2"); - assertThat(result).isNotNull(); - }).then(Mono.fromCallable(() -> { - executionOrder.set(executionOrder.get() + "3"); - return new CallToolResult("Async ping test completed", false); - })); - }); + executionOrder.set(executionOrder.get() + "2"); + assertThat(result).isNotNull(); + }).then(Mono.fromCallable(() -> { + executionOrder.set(executionOrder.get() + "3"); + return new CallToolResult("Async ping test completed", false); + })); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java index b7a9e4a09..e854c37d4 100644 --- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java +++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java @@ -3,6 +3,11 @@ */ package io.modelcontextprotocol.server; +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatExceptionOfType; +import static org.awaitility.Awaitility.await; +import static org.mockito.Mockito.mock; + import java.time.Duration; import java.util.List; import java.util.Map; @@ -10,7 +15,20 @@ import java.util.concurrent.atomic.AtomicReference; import java.util.function.Function; +import org.apache.catalina.LifecycleException; +import org.apache.catalina.LifecycleState; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.client.RestClient; +import org.springframework.web.servlet.config.annotation.EnableWebMvc; +import org.springframework.web.servlet.function.RouterFunction; +import org.springframework.web.servlet.function.ServerResponse; + import com.fasterxml.jackson.databind.ObjectMapper; + import io.modelcontextprotocol.client.McpClient; import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport; import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider; @@ -26,27 +44,10 @@ import io.modelcontextprotocol.spec.McpSchema.Root; import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities; import io.modelcontextprotocol.spec.McpSchema.Tool; -import org.apache.catalina.LifecycleException; -import org.apache.catalina.LifecycleState; -import org.junit.jupiter.api.AfterEach; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; import reactor.core.publisher.Mono; import reactor.core.scheduler.Schedulers; import reactor.test.StepVerifier; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; -import org.springframework.web.client.RestClient; -import org.springframework.web.servlet.config.annotation.EnableWebMvc; -import org.springframework.web.servlet.function.RouterFunction; -import org.springframework.web.servlet.function.ServerResponse; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatExceptionOfType; -import static org.awaitility.Awaitility.await; -import static org.mockito.Mockito.mock; - class WebMvcSseIntegrationTests { private static final int PORT = TestUtil.findAvailablePort(); @@ -122,13 +123,13 @@ public void after() { @Test void testCreateMessageWithoutSamplingCapabilities() { - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - - exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block(); - - return Mono.just(mock(CallToolResult.class)); - }); + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block(); + return Mono.just(mock(CallToolResult.class)); + }) + .build(); //@formatter:off var server = McpServer.async(mcpServerTransportProvider) @@ -169,31 +170,33 @@ void testCreateMessageSuccess() { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - - var createMessageRequest = McpSchema.CreateMessageRequest.builder() - .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, - new McpSchema.TextContent("Test message")))) - .modelPreferences(ModelPreferences.builder() - .hints(List.of()) - .costPriority(1.0) - .speedPriority(1.0) - .intelligencePriority(1.0) - .build()) - .build(); - - StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.role()).isEqualTo(Role.USER); - assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class); - assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message"); - assertThat(result.model()).isEqualTo("MockModelName"); - assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE); - }).verifyComplete(); - - return Mono.just(callResponse); - }); + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + + var createMessageRequest = McpSchema.CreateMessageRequest.builder() + .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, + new McpSchema.TextContent("Test message")))) + .modelPreferences(ModelPreferences.builder() + .hints(List.of()) + .costPriority(1.0) + .speedPriority(1.0) + .intelligencePriority(1.0) + .build()) + .build(); + + StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.role()).isEqualTo(Role.USER); + assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class); + assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message"); + assertThat(result.model()).isEqualTo("MockModelName"); + assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE); + }).verifyComplete(); + + return Mono.just(callResponse); + }) + .build(); //@formatter:off var mcpServer = McpServer.async(mcpServerTransportProvider) @@ -245,31 +248,33 @@ void testCreateMessageWithRequestTimeoutSuccess() throws InterruptedException { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - - var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() - .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, - new McpSchema.TextContent("Test message")))) - .modelPreferences(ModelPreferences.builder() - .hints(List.of()) - .costPriority(1.0) - .speedPriority(1.0) - .intelligencePriority(1.0) - .build()) - .build(); - - StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.role()).isEqualTo(Role.USER); - assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class); - assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message"); - assertThat(result.model()).isEqualTo("MockModelName"); - assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE); - }).verifyComplete(); - - return Mono.just(callResponse); - }); + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + + var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() + .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, + new McpSchema.TextContent("Test message")))) + .modelPreferences(ModelPreferences.builder() + .hints(List.of()) + .costPriority(1.0) + .speedPriority(1.0) + .intelligencePriority(1.0) + .build()) + .build(); + + StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.role()).isEqualTo(Role.USER); + assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class); + assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message"); + assertThat(result.model()).isEqualTo("MockModelName"); + assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE); + }).verifyComplete(); + + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -317,31 +322,33 @@ void testCreateMessageWithRequestTimeoutFail() throws InterruptedException { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - - var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() - .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, - new McpSchema.TextContent("Test message")))) - .modelPreferences(ModelPreferences.builder() - .hints(List.of()) - .costPriority(1.0) - .speedPriority(1.0) - .intelligencePriority(1.0) - .build()) - .build(); - - StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.role()).isEqualTo(Role.USER); - assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class); - assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message"); - assertThat(result.model()).isEqualTo("MockModelName"); - assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE); - }).verifyComplete(); - - return Mono.just(callResponse); - }); + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + + var craeteMessageRequest = McpSchema.CreateMessageRequest.builder() + .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER, + new McpSchema.TextContent("Test message")))) + .modelPreferences(ModelPreferences.builder() + .hints(List.of()) + .costPriority(1.0) + .speedPriority(1.0) + .intelligencePriority(1.0) + .build()) + .build(); + + StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.role()).isEqualTo(Role.USER); + assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class); + assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message"); + assertThat(result.model()).isEqualTo("MockModelName"); + assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE); + }).verifyComplete(); + + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -366,13 +373,15 @@ void testCreateMessageWithRequestTimeoutFail() throws InterruptedException { @Test void testCreateElicitationWithoutElicitationCapabilities() { - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - exchange.createElicitation(mock(McpSchema.ElicitRequest.class)).block(); + exchange.createElicitation(mock(McpSchema.ElicitRequest.class)).block(); - return Mono.just(mock(CallToolResult.class)); - }); + return Mono.just(mock(CallToolResult.class)); + }) + .build(); var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build(); @@ -407,23 +416,25 @@ void testCreateElicitationSuccess() { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - var elicitationRequest = McpSchema.ElicitRequest.builder() - .message("Test message") - .requestedSchema( - Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) - .build(); + var elicitationRequest = McpSchema.ElicitRequest.builder() + .message("Test message") + .requestedSchema( + Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) + .build(); - StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT); - assertThat(result.content().get("message")).isEqualTo("Test message"); - }).verifyComplete(); + StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT); + assertThat(result.content().get("message")).isEqualTo("Test message"); + }).verifyComplete(); - return Mono.just(callResponse); - }); + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -474,23 +485,25 @@ void testCreateElicitationWithRequestTimeoutSuccess() { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - var elicitationRequest = McpSchema.ElicitRequest.builder() - .message("Test message") - .requestedSchema( - Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) - .build(); + var elicitationRequest = McpSchema.ElicitRequest.builder() + .message("Test message") + .requestedSchema( + Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) + .build(); - StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT); - assertThat(result.content().get("message")).isEqualTo("Test message"); - }).verifyComplete(); + StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT); + assertThat(result.content().get("message")).isEqualTo("Test message"); + }).verifyComplete(); - return Mono.just(callResponse); - }); + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -538,23 +551,25 @@ void testCreateElicitationWithRequestTimeoutFail() { CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - var elicitationRequest = McpSchema.ElicitRequest.builder() - .message("Test message") - .requestedSchema( - Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) - .build(); + var elicitationRequest = McpSchema.ElicitRequest.builder() + .message("Test message") + .requestedSchema( + Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string")))) + .build(); - StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { - assertThat(result).isNotNull(); - assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT); - assertThat(result.content().get("message")).isEqualTo("Test message"); - }).verifyComplete(); + StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> { + assertThat(result).isNotNull(); + assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT); + assertThat(result.content().get("message")).isEqualTo("Test message"); + }).verifyComplete(); - return Mono.just(callResponse); - }); + return Mono.just(callResponse); + }) + .build(); var mcpServer = McpServer.async(mcpServerTransportProvider) .serverInfo("test-server", "1.0.0") @@ -623,13 +638,15 @@ void testRootsSuccess() { @Test void testRootsWithoutCapability() { - McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { + McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { - exchange.listRoots(); // try to list roots + exchange.listRoots(); // try to list roots - return mock(CallToolResult.class); - }); + return mock(CallToolResult.class); + }) + .build(); var mcpServer = McpServer.sync(mcpServerTransportProvider).rootsChangeHandler((exchange, rootsUpdate) -> { }).tools(tool).build(); @@ -750,17 +767,19 @@ void testRootsServerCloseWithActiveSubscription() { void testToolCallSuccess() { var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - // perform a blocking call to a remote service - String response = RestClient.create() - .get() - .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") - .retrieve() - .body(String.class); - assertThat(response).isNotBlank(); - return callResponse; - }); + McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + // perform a blocking call to a remote service + String response = RestClient.create() + .get() + .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") + .retrieve() + .body(String.class); + assertThat(response).isNotBlank(); + return callResponse; + }) + .build(); var mcpServer = McpServer.sync(mcpServerTransportProvider) .capabilities(ServerCapabilities.builder().tools(true).build()) @@ -813,17 +832,19 @@ void testThrowingToolCallIsCaughtBeforeTimeout() { void testToolListChangeHandlingSuccess() { var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null); - McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> { - // perform a blocking call to a remote service - String response = RestClient.create() - .get() - .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") - .retrieve() - .body(String.class); - assertThat(response).isNotBlank(); - return callResponse; - }); + McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema)) + .callHandler((exchange, request) -> { + // perform a blocking call to a remote service + String response = RestClient.create() + .get() + .uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md") + .retrieve() + .body(String.class); + assertThat(response).isNotBlank(); + return callResponse; + }) + .build(); AtomicReference> rootsRef = new AtomicReference<>(); @@ -864,9 +885,10 @@ void testToolListChangeHandlingSuccess() { }); // Add a new tool - McpServerFeatures.SyncToolSpecification tool2 = new McpServerFeatures.SyncToolSpecification( - new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema), - (exchange, request) -> callResponse); + McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder() + .tool(new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema)) + .callHandler((exchange, request) -> callResponse) + .build(); mcpServer.addTool(tool2); diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java index 1f6730638..eb08bdcde 100644 --- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java +++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java @@ -34,7 +34,6 @@ * * @author Christian Tzolov */ -// KEEP IN SYNC with the class in mcp-test module public abstract class AbstractMcpAsyncServerTests { private static final String TEST_TOOL_NAME = "test-tool"; @@ -102,6 +101,7 @@ void testImmediateClose() { """; @Test + @Deprecated void testAddTool() { Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema); var mcpAsyncServer = McpServer.async(createMcpTransportProvider()) @@ -117,6 +117,23 @@ void testAddTool() { } @Test + void testAddToolCall() { + Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema); + var mcpAsyncServer = McpServer.async(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .build(); + + StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder() + .tool(newTool) + .callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .build())).verifyComplete(); + + assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException(); + } + + @Test + @Deprecated void testAddDuplicateTool() { Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema); @@ -137,6 +154,83 @@ void testAddDuplicateTool() { assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException(); } + @Test + void testAddDuplicateToolCall() { + Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema); + + var mcpAsyncServer = McpServer.async(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .build(); + + StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .build())).verifyErrorSatisfies(error -> { + assertThat(error).isInstanceOf(McpError.class) + .hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists"); + }); + + assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException(); + } + + @Test + void testDuplicateToolCallDuringBuilding() { + Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building", + emptyJsonSchema); + + assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) // Duplicate! + .build()).isInstanceOf(IllegalArgumentException.class) + .hasMessage("Tool with name 'duplicate-build-toolcall' is already registered."); + } + + @Test + void testDuplicateToolsInBatchListRegistration() { + Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema); + List specs = List.of( + McpServerFeatures.AsyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .build(), + McpServerFeatures.AsyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .build() // Duplicate! + ); + + assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .tools(specs) + .build()).isInstanceOf(IllegalArgumentException.class) + .hasMessage("Tool with name 'batch-list-tool' is already registered."); + } + + @Test + void testDuplicateToolsInBatchVarargsRegistration() { + Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema); + + assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .tools(McpServerFeatures.AsyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .build(), + McpServerFeatures.AsyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) + .build() // Duplicate! + ) + .build()).isInstanceOf(IllegalArgumentException.class) + .hasMessage("Tool with name 'batch-varargs-tool' is already registered."); + } + @Test void testRemoveTool() { Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema); @@ -144,7 +238,7 @@ void testRemoveTool() { var mcpAsyncServer = McpServer.async(createMcpTransportProvider()) .serverInfo("test-server", "1.0.0") .capabilities(ServerCapabilities.builder().tools(true).build()) - .tool(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false))) + .toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) .build(); StepVerifier.create(mcpAsyncServer.removeTool(TEST_TOOL_NAME)).verifyComplete(); @@ -173,7 +267,7 @@ void testNotifyToolsListChanged() { var mcpAsyncServer = McpServer.async(createMcpTransportProvider()) .serverInfo("test-server", "1.0.0") .capabilities(ServerCapabilities.builder().tools(true).build()) - .tool(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false))) + .toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false))) .build(); StepVerifier.create(mcpAsyncServer.notifyToolsListChanged()).verifyComplete(); diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java index 5dac6f6a5..4d5f9f772 100644 --- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java +++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java @@ -4,8 +4,16 @@ package io.modelcontextprotocol.server; +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatCode; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + import java.util.List; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + import io.modelcontextprotocol.spec.McpError; import io.modelcontextprotocol.spec.McpSchema; import io.modelcontextprotocol.spec.McpSchema.CallToolResult; @@ -17,21 +25,13 @@ import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities; import io.modelcontextprotocol.spec.McpSchema.Tool; import io.modelcontextprotocol.spec.McpServerTransportProvider; -import org.junit.jupiter.api.AfterEach; -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatCode; -import static org.assertj.core.api.Assertions.assertThatThrownBy; /** * Test suite for the {@link McpSyncServer} that can be used with different - * {@link io.modelcontextprotocol.spec.McpServerTransportProvider} implementations. + * {@link McpTransportProvider} implementations. * * @author Christian Tzolov */ -// KEEP IN SYNC with the class in mcp-test module public abstract class AbstractMcpSyncServerTests { private static final String TEST_TOOL_NAME = "test-tool"; @@ -109,6 +109,7 @@ void testGetAsyncServer() { """; @Test + @Deprecated void testAddTool() { var mcpSyncServer = McpServer.sync(createMcpTransportProvider()) .serverInfo("test-server", "1.0.0") @@ -124,6 +125,23 @@ void testAddTool() { } @Test + void testAddToolCall() { + var mcpSyncServer = McpServer.sync(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .build(); + + Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema); + assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder() + .tool(newTool) + .callHandler((exchange, request) -> new CallToolResult(List.of(), false)) + .build())).doesNotThrowAnyException(); + + assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException(); + } + + @Test + @Deprecated void testAddDuplicateTool() { Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema); @@ -141,6 +159,81 @@ void testAddDuplicateTool() { assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException(); } + @Test + void testAddDuplicateToolCall() { + Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema); + + var mcpSyncServer = McpServer.sync(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) + .build(); + + assertThatThrownBy(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> new CallToolResult(List.of(), false)) + .build())).isInstanceOf(McpError.class) + .hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists"); + + assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException(); + } + + @Test + void testDuplicateToolCallDuringBuilding() { + Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building", + emptyJsonSchema); + + assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) + .toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) // Duplicate! + .build()).isInstanceOf(IllegalArgumentException.class) + .hasMessage("Tool with name 'duplicate-build-toolcall' is already registered."); + } + + @Test + void testDuplicateToolsInBatchListRegistration() { + Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema); + List specs = List.of( + McpServerFeatures.SyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> new CallToolResult(List.of(), false)) + .build(), + McpServerFeatures.SyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> new CallToolResult(List.of(), false)) + .build() // Duplicate! + ); + + assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .tools(specs) + .build()).isInstanceOf(IllegalArgumentException.class) + .hasMessage("Tool with name 'batch-list-tool' is already registered."); + } + + @Test + void testDuplicateToolsInBatchVarargsRegistration() { + Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema); + + assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider()) + .serverInfo("test-server", "1.0.0") + .capabilities(ServerCapabilities.builder().tools(true).build()) + .tools(McpServerFeatures.SyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> new CallToolResult(List.of(), false)) + .build(), + McpServerFeatures.SyncToolSpecification.builder() + .tool(duplicateTool) + .callHandler((exchange, request) -> new CallToolResult(List.of(), false)) + .build() // Duplicate! + ) + .build()).isInstanceOf(IllegalArgumentException.class) + .hasMessage("Tool with name 'batch-varargs-tool' is already registered."); + } + @Test void testRemoveTool() { Tool tool = new McpSchema.Tool(TEST_TOOL_NAME, "Test tool", emptyJsonSchema); @@ -148,7 +241,7 @@ void testRemoveTool() { var mcpSyncServer = McpServer.sync(createMcpTransportProvider()) .serverInfo("test-server", "1.0.0") .capabilities(ServerCapabilities.builder().tools(true).build()) - .tool(tool, (exchange, args) -> new CallToolResult(List.of(), false)) + .toolCall(tool, (exchange, args) -> new CallToolResult(List.of(), false)) .build(); assertThatCode(() -> mcpSyncServer.removeTool(TEST_TOOL_NAME)).doesNotThrowAnyException(); diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java index 6efe58de4..5c8423b6d 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java +++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java @@ -268,7 +268,7 @@ private McpServerSession.NotificationHandler asyncRootsListChangedNotificationHa // --------------------------------------- /** - * Add a new tool specification at runtime. + * Add a new tool call specification at runtime. * @param toolSpecification The tool specification to add * @return Mono that completes when clients have been notified of the change */ @@ -279,7 +279,7 @@ public Mono addTool(McpServerFeatures.AsyncToolSpecification toolSpecifica if (toolSpecification.tool() == null) { return Mono.error(new McpError("Tool must not be null")); } - if (toolSpecification.call() == null) { + if (toolSpecification.call() == null && toolSpecification.callHandler() == null) { return Mono.error(new McpError("Tool call handler must not be null")); } if (this.serverCapabilities.tools() == null) { @@ -360,7 +360,7 @@ private McpServerSession.RequestHandler toolsCallRequestHandler( return Mono.error(new McpError("Tool not found: " + callToolRequest.name())); } - return toolSpecification.map(tool -> tool.call().apply(exchange, callToolRequest.arguments())) + return toolSpecification.map(tool -> tool.callHandler().apply(exchange, callToolRequest)) .orElse(Mono.error(new McpError("Tool not found: " + callToolRequest.name()))); }; } diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java index 637b7f92a..63b589223 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java +++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java @@ -82,12 +82,16 @@ * .capabilities(new ServerCapabilities(...)) * // Register tools * .tools( - * new McpServerFeatures.AsyncToolSpecification(calculatorTool, - * (exchange, args) -> Mono.fromSupplier(() -> calculate(args)) - * .map(result -> new CallToolResult("Result: " + result))), - * new McpServerFeatures.AsyncToolSpecification(weatherTool, - * (exchange, args) -> Mono.fromSupplier(() -> getWeather(args)) - * .map(result -> new CallToolResult("Weather: " + result))) + * McpServerFeatures.AsyncToolSpecification.builder() + * .tool(calculatorTool) + * .callTool((exchange, args) -> Mono.fromSupplier(() -> calculate(args.arguments())) + * .map(result -> new CallToolResult("Result: " + result)))) + *. .build(), + * McpServerFeatures.AsyncToolSpecification.builder() + * .tool((weatherTool) + * .callTool((exchange, args) -> Mono.fromSupplier(() -> getWeather(args.arguments())) + * .map(result -> new CallToolResult("Weather: " + result)))) + * .build() * ) * // Register resources * .resources( @@ -321,17 +325,47 @@ public AsyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabi * map of arguments passed to the tool. * @return This builder instance for method chaining * @throws IllegalArgumentException if tool or handler is null + * @deprecated Use {@link #toolCall(McpSchema.Tool, BiFunction)} instead for tool + * calls that require a request object. */ + @Deprecated public AsyncSpecification tool(McpSchema.Tool tool, BiFunction, Mono> handler) { Assert.notNull(tool, "Tool must not be null"); Assert.notNull(handler, "Handler must not be null"); + assertNoDuplicateTool(tool.name()); this.tools.add(new McpServerFeatures.AsyncToolSpecification(tool, handler)); return this; } + /** + * Adds a single tool with its implementation handler to the server. This is a + * convenience method for registering individual tools without creating a + * {@link McpServerFeatures.AsyncToolSpecification} explicitly. + * @param tool The tool definition including name, description, and schema. Must + * not be null. + * @param callHandler The function that implements the tool's logic. Must not be + * null. The function's first argument is an {@link McpAsyncServerExchange} upon + * which the server can interact with the connected client. The second argument is + * the {@link McpSchema.CallToolRequest} object containing the tool call + * @return This builder instance for method chaining + * @throws IllegalArgumentException if tool or handler is null + */ + public AsyncSpecification toolCall(McpSchema.Tool tool, + BiFunction> callHandler) { + + Assert.notNull(tool, "Tool must not be null"); + Assert.notNull(callHandler, "Handler must not be null"); + assertNoDuplicateTool(tool.name()); + + this.tools + .add(McpServerFeatures.AsyncToolSpecification.builder().tool(tool).callHandler(callHandler).build()); + + return this; + } + /** * Adds multiple tools with their handlers to the server using a List. This method * is useful when tools are dynamically generated or loaded from a configuration @@ -344,7 +378,12 @@ public AsyncSpecification tool(McpSchema.Tool tool, */ public AsyncSpecification tools(List toolSpecifications) { Assert.notNull(toolSpecifications, "Tool handlers list must not be null"); - this.tools.addAll(toolSpecifications); + + for (var tool : toolSpecifications) { + assertNoDuplicateTool(tool.tool().name()); + this.tools.add(tool); + } + return this; } @@ -355,24 +394,31 @@ public AsyncSpecification tools(List t *

* Example usage: 

{@code
 		 * .tools(
-		 *     new McpServerFeatures.AsyncToolSpecification(calculatorTool, calculatorHandler),
-		 *     new McpServerFeatures.AsyncToolSpecification(weatherTool, weatherHandler),
-		 *     new McpServerFeatures.AsyncToolSpecification(fileManagerTool, fileManagerHandler)
+		 *     McpServerFeatures.AsyncToolSpecification.builder().tool(calculatorTool).callTool(calculatorHandler).build(),
+		 *     McpServerFeatures.AsyncToolSpecification.builder().tool(weatherTool).callTool(weatherHandler).build(),
+		 *     McpServerFeatures.AsyncToolSpecification.builder().tool(fileManagerTool).callTool(fileManagerHandler).build()
 		 * )
 		 * }
* @param toolSpecifications The tool specifications to add. Must not be null. * @return This builder instance for method chaining * @throws IllegalArgumentException if toolSpecifications is null - * @see #tools(List) */ public AsyncSpecification tools(McpServerFeatures.AsyncToolSpecification... toolSpecifications) { Assert.notNull(toolSpecifications, "Tool handlers list must not be null"); + for (McpServerFeatures.AsyncToolSpecification tool : toolSpecifications) { + assertNoDuplicateTool(tool.tool().name()); this.tools.add(tool); } return this; } + private void assertNoDuplicateTool(String toolName) { + if (this.tools.stream().anyMatch(toolSpec -> toolSpec.tool().name().equals(toolName))) { + throw new IllegalArgumentException("Tool with name '" + toolName + "' is already registered."); + } + } + /** * Registers multiple resources with their handlers using a Map. This method is * useful when resources are dynamically generated or loaded from a configuration @@ -814,17 +860,45 @@ public SyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabil * list of arguments passed to the tool. * @return This builder instance for method chaining * @throws IllegalArgumentException if tool or handler is null + * @deprecated Use {@link #toolCall(McpSchema.Tool, BiFunction)} instead for tool + * calls that require a request object. */ + @Deprecated public SyncSpecification tool(McpSchema.Tool tool, BiFunction, McpSchema.CallToolResult> handler) { Assert.notNull(tool, "Tool must not be null"); Assert.notNull(handler, "Handler must not be null"); + assertNoDuplicateTool(tool.name()); this.tools.add(new McpServerFeatures.SyncToolSpecification(tool, handler)); return this; } + /** + * Adds a single tool with its implementation handler to the server. This is a + * convenience method for registering individual tools without creating a + * {@link McpServerFeatures.SyncToolSpecification} explicitly. + * @param tool The tool definition including name, description, and schema. Must + * not be null. + * @param handler The function that implements the tool's logic. Must not be null. + * The function's first argument is an {@link McpSyncServerExchange} upon which + * the server can interact with the connected client. The second argument is the + * list of arguments passed to the tool. + * @return This builder instance for method chaining + * @throws IllegalArgumentException if tool or handler is null + */ + public SyncSpecification toolCall(McpSchema.Tool tool, + BiFunction handler) { + Assert.notNull(tool, "Tool must not be null"); + Assert.notNull(handler, "Handler must not be null"); + assertNoDuplicateTool(tool.name()); + + this.tools.add(new McpServerFeatures.SyncToolSpecification(tool, null, handler)); + + return this; + } + /** * Adds multiple tools with their handlers to the server using a List. This method * is useful when tools are dynamically generated or loaded from a configuration @@ -837,7 +911,13 @@ public SyncSpecification tool(McpSchema.Tool tool, */ public SyncSpecification tools(List toolSpecifications) { Assert.notNull(toolSpecifications, "Tool handlers list must not be null"); - this.tools.addAll(toolSpecifications); + + for (var tool : toolSpecifications) { + String toolName = tool.tool().name(); + assertNoDuplicateTool(toolName); // Check against existing tools + this.tools.add(tool); + } + return this; } @@ -860,12 +940,20 @@ public SyncSpecification tools(List too */ public SyncSpecification tools(McpServerFeatures.SyncToolSpecification... toolSpecifications) { Assert.notNull(toolSpecifications, "Tool handlers list must not be null"); + for (McpServerFeatures.SyncToolSpecification tool : toolSpecifications) { + assertNoDuplicateTool(tool.tool().name()); this.tools.add(tool); } return this; } + private void assertNoDuplicateTool(String toolName) { + if (this.tools.stream().anyMatch(toolSpec -> toolSpec.tool().name().equals(toolName))) { + throw new IllegalArgumentException("Tool with name '" + toolName + "' is already registered."); + } + } + /** * Registers multiple resources with their handlers using a Map. This method is * useful when resources are dynamically generated or loaded from a configuration diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java index e61722a82..3ce599c8b 100644 --- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java +++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java @@ -12,6 +12,7 @@ import java.util.function.BiFunction; import io.modelcontextprotocol.spec.McpSchema; +import io.modelcontextprotocol.spec.McpSchema.CallToolRequest; import io.modelcontextprotocol.util.Assert; import io.modelcontextprotocol.util.Utils; import reactor.core.publisher.Mono; @@ -205,51 +206,110 @@ record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities se /** * Specification of a tool with its asynchronous handler function. Tools are the * primary way for MCP servers to expose functionality to AI models. Each tool - * represents a specific capability, such as: - *
    - *
  • Performing calculations - *
  • Accessing external APIs - *
  • Querying databases - *
  • Manipulating files - *
  • Executing system commands - *
- * - *

- * Example tool specification: 

{@code
-	 * new McpServerFeatures.AsyncToolSpecification(
-	 *     new Tool(
-	 *         "calculator",
-	 *         "Performs mathematical calculations",
-	 *         new JsonSchemaObject()
-	 *             .required("expression")
-	 *             .property("expression", JsonSchemaType.STRING)
-	 *     ),
-	 *     (exchange, args) -> {
-	 *         String expr = (String) args.get("expression");
-	 *         return Mono.fromSupplier(() -> evaluate(expr))
-	 *             .map(result -> new CallToolResult("Result: " + result));
-	 *     }
-	 * )
-	 * }
+ * represents a specific capability. * * @param tool The tool definition including name, description, and parameter schema - * @param call The function that implements the tool's logic, receiving arguments and - * returning results. The function's first argument is an - * {@link McpAsyncServerExchange} upon which the server can interact with the - * connected client. The second arguments is a map of tool arguments. + * @param call Deprecated. Uset he {@link AsyncToolSpecification#callHandler} instead. + * @param callHandler The function that implements the tool's logic, receiving a + * {@link McpAsyncServerExchange} and a + * {@link io.modelcontextprotocol.spec.McpSchema.CallToolRequest} and returning + * results. The function's first argument is an {@link McpAsyncServerExchange} upon + * which the server can interact with the connected client. The second arguments is a + * map of tool arguments. */ public record AsyncToolSpecification(McpSchema.Tool tool, - BiFunction, Mono> call) { + @Deprecated BiFunction, Mono> call, + BiFunction> callHandler) { + + /** + * @deprecated Use {@link AsyncToolSpecification(McpSchema.Tool, null, + * BiFunction)} instead. + **/ + @Deprecated + public AsyncToolSpecification(McpSchema.Tool tool, + BiFunction, Mono> call) { + this(tool, call, (exchange, toolReq) -> call.apply(exchange, toolReq.arguments())); + } + + static AsyncToolSpecification fromSync(SyncToolSpecification syncToolSpec) { + return fromSync(syncToolSpec, false); + } + + static AsyncToolSpecification fromSync(SyncToolSpecification syncToolSpec, boolean immediate) { - static AsyncToolSpecification fromSync(SyncToolSpecification tool, boolean immediate) { // FIXME: This is temporary, proper validation should be implemented - if (tool == null) { + if (syncToolSpec == null) { return null; } - return new AsyncToolSpecification(tool.tool(), (exchange, map) -> { - var toolResult = Mono.fromCallable(() -> tool.call().apply(new McpSyncServerExchange(exchange), map)); + + BiFunction, Mono> deprecatedCall = (syncToolSpec + .call() != null) ? (exchange, map) -> { + var toolResult = Mono + .fromCallable(() -> syncToolSpec.call().apply(new McpSyncServerExchange(exchange), map)); + return immediate ? toolResult : toolResult.subscribeOn(Schedulers.boundedElastic()); + } : null; + + BiFunction> callHandler = ( + exchange, req) -> { + var toolResult = Mono + .fromCallable(() -> syncToolSpec.callHandler().apply(new McpSyncServerExchange(exchange), req)); return immediate ? toolResult : toolResult.subscribeOn(Schedulers.boundedElastic()); - }); + }; + + return new AsyncToolSpecification(syncToolSpec.tool(), deprecatedCall, callHandler); + } + + /** + * Builder for creating AsyncToolSpecification instances. + */ + public static class Builder { + + private McpSchema.Tool tool; + + private BiFunction> callHandler; + + /** + * Sets the tool definition. + * @param tool The tool definition including name, description, and parameter + * schema + * @return this builder instance + */ + public Builder tool(McpSchema.Tool tool) { + this.tool = tool; + return this; + } + + /** + * Sets the call tool handler function. + * @param callHandler The function that implements the tool's logic + * @return this builder instance + */ + public Builder callHandler( + BiFunction> callHandler) { + this.callHandler = callHandler; + return this; + } + + /** + * Builds the AsyncToolSpecification instance. + * @return a new AsyncToolSpecification instance + * @throws IllegalArgumentException if required fields are not set + */ + public AsyncToolSpecification build() { + Assert.notNull(tool, "Tool must not be null"); + Assert.notNull(callHandler, "Call handler function must not be null"); + + return new AsyncToolSpecification(tool, null, callHandler); + } + + } + + /** + * Creates a new builder instance. + * @return a new Builder instance + */ + public static Builder builder() { + return new Builder(); } } @@ -265,13 +325,13 @@ static AsyncToolSpecification fromSync(SyncToolSpecification tool, boolean immed * * *

- * Example resource specification: 

{@code
+	 * Example resource specification:
+	 *
+	 * 
{@code
 	 * new McpServerFeatures.AsyncResourceSpecification(
-	 *     new Resource("docs", "Documentation files", "text/markdown"),
-	 *     (exchange, request) ->
-	 *         Mono.fromSupplier(() -> readFile(request.getPath()))
-	 *             .map(ReadResourceResult::new)
-	 * )
+	 * 		new Resource("docs", "Documentation files", "text/markdown"),
+	 * 		(exchange, request) -> Mono.fromSupplier(() -> readFile(request.getPath()))
+	 * 				.map(ReadResourceResult::new))
 	 * }

 	 *
 	 * @param resource The resource definition including name, description, and MIME type
@@ -308,16 +368,16 @@ static AsyncResourceSpecification fromSync(SyncResourceSpecification resource, b
 	 * 
 	 *
 	 * 

-	 * Example prompt specification: 
{@code
+	 * Example prompt specification:
+	 *
+	 * 
{@code
 	 * new McpServerFeatures.AsyncPromptSpecification(
-	 *     new Prompt("analyze", "Code analysis template"),
-	 *     (exchange, request) -> {
-	 *         String code = request.getArguments().get("code");
-	 *         return Mono.just(new GetPromptResult(
-	 *             "Analyze this code:\n\n" + code + "\n\nProvide feedback on:"
-	 *         ));
-	 *     }
-	 * )
+	 * 		new Prompt("analyze", "Code analysis template"),
+	 * 		(exchange, request) -> {
+	 * 			String code = request.getArguments().get("code");
+	 * 			return Mono.just(new GetPromptResult(
+	 * 					"Analyze this code:\n\n" + code + "\n\nProvide feedback on:"));
+	 * 		})
 	 * }

 	 *
 	 * @param prompt The prompt definition including name and description
@@ -386,41 +446,99 @@ static AsyncCompletionSpecification fromSync(SyncCompletionSpecification complet
 
 	/**
 	 * Specification of a tool with its synchronous handler function. Tools are the
-	 * primary way for MCP servers to expose functionality to AI models. Each tool
-	 * represents a specific capability, such as:
-	 * 
    
-	 * 
  • Performing calculations
-	 * 
  • Accessing external APIs
-	 * 
  • Querying databases
-	 * 
  • Manipulating files
-	 * 
  • Executing system commands
-	 * 

+	 * primary way for MCP servers to expose functionality to AI models.
 	 *
 	 * 

-	 * Example tool specification: 
{@code
-	 * new McpServerFeatures.SyncToolSpecification(
-	 *     new Tool(
-	 *         "calculator",
-	 *         "Performs mathematical calculations",
-	 *         new JsonSchemaObject()
-	 *             .required("expression")
-	 *             .property("expression", JsonSchemaType.STRING)
-	 *     ),
-	 *     (exchange, args) -> {
-	 *         String expr = (String) args.get("expression");
-	 *         return new CallToolResult("Result: " + evaluate(expr));
-	 *     }
-	 * )
+	 * Example tool specification:
+	 *
+	 * 
{@code
+	 * McpServerFeatures.SyncToolSpecification.builder()
+	 * 		.tool(new Tool(
+	 * 				"calculator",
+	 * 				"Performs mathematical calculations",
+	 * 				new JsonSchemaObject()
+	 * 						.required("expression")
+	 * 						.property("expression", JsonSchemaType.STRING)))
+	 * 		.toolHandler((exchange, req) -> {
+	 * 			String expr = (String) req.arguments().get("expression");
+	 * 			return new CallToolResult("Result: " + evaluate(expr));
+	 * 		}))
+	 *      .build();
 	 * }

 	 *
 	 * @param tool The tool definition including name, description, and parameter schema
-	 * @param call The function that implements the tool's logic, receiving arguments and
-	 * returning results. The function's first argument is an
+	 * @param call (Deprected) The function that implements the tool's logic, receiving
+	 * arguments and returning results. The function's first argument is an
 	 * {@link McpSyncServerExchange} upon which the server can interact with the connected
-	 * client. The second arguments is a map of arguments passed to the tool.
+	 * @param callHandler The function that implements the tool's logic, receiving a
+	 * {@link McpSyncServerExchange} and a
+	 * {@link io.modelcontextprotocol.spec.McpSchema.CallToolRequest} and returning
+	 * results. The function's first argument is an {@link McpSyncServerExchange} upon
+	 * which the server can interact with the client. The second arguments is a map of
+	 * arguments passed to the tool.
 	 */
 	public record SyncToolSpecification(McpSchema.Tool tool,
-			BiFunction, McpSchema.CallToolResult> call) {
+			@Deprecated BiFunction, McpSchema.CallToolResult> call,
+			BiFunction callHandler) {
+
+		@Deprecated
+		public SyncToolSpecification(McpSchema.Tool tool,
+				BiFunction, McpSchema.CallToolResult> call) {
+			this(tool, call, (exchange, toolReq) -> call.apply(exchange, toolReq.arguments()));
+		}
+
+		/**
+		 * Builder for creating SyncToolSpecification instances.
+		 */
+		public static class Builder {
+
+			private McpSchema.Tool tool;
+
+			private BiFunction callHandler;
+
+			/**
+			 * Sets the tool definition.
+			 * @param tool The tool definition including name, description, and parameter
+			 * schema
+			 * @return this builder instance
+			 */
+			public Builder tool(McpSchema.Tool tool) {
+				this.tool = tool;
+				return this;
+			}
+
+			/**
+			 * Sets the call tool handler function.
+			 * @param callHandler The function that implements the tool's logic
+			 * @return this builder instance
+			 */
+			public Builder callHandler(
+					BiFunction callHandler) {
+				this.callHandler = callHandler;
+				return this;
+			}
+
+			/**
+			 * Builds the SyncToolSpecification instance.
+			 * @return a new SyncToolSpecification instance
+			 * @throws IllegalArgumentException if required fields are not set
+			 */
+			public SyncToolSpecification build() {
+				Assert.notNull(tool, "Tool must not be null");
+				Assert.notNull(callHandler, "CallTool function must not be null");
+
+				return new SyncToolSpecification(tool, null, callHandler);
+			}
+
+		}
+
+		/**
+		 * Creates a new builder instance.
+		 * @return a new Builder instance
+		 */
+		public static Builder builder() {
+			return new Builder();
+		}
 	}
 
 	/**
@@ -435,14 +553,15 @@ public record SyncToolSpecification(McpSchema.Tool tool,
 	 * 
 	 *
 	 * 

-	 * Example resource specification: 
{@code
+	 * Example resource specification:
+	 *
+	 * 
{@code
 	 * new McpServerFeatures.SyncResourceSpecification(
-	 *     new Resource("docs", "Documentation files", "text/markdown"),
-	 *     (exchange, request) -> {
-	 *         String content = readFile(request.getPath());
-	 *         return new ReadResourceResult(content);
-	 *     }
-	 * )
+	 * 		new Resource("docs", "Documentation files", "text/markdown"),
+	 * 		(exchange, request) -> {
+	 * 			String content = readFile(request.getPath());
+	 * 			return new ReadResourceResult(content);
+	 * 		})
 	 * }

 	 *
 	 * @param resource The resource definition including name, description, and MIME type
@@ -467,16 +586,16 @@ public record SyncResourceSpecification(McpSchema.Resource resource,
 	 * 
 	 *
 	 * 

-	 * Example prompt specification: 
{@code
+	 * Example prompt specification:
+	 *
+	 * 
{@code
 	 * new McpServerFeatures.SyncPromptSpecification(
-	 *     new Prompt("analyze", "Code analysis template"),
-	 *     (exchange, request) -> {
-	 *         String code = request.getArguments().get("code");
-	 *         return new GetPromptResult(
-	 *             "Analyze this code:\n\n" + code + "\n\nProvide feedback on:"
-	 *         );
-	 *     }
-	 * )
+	 * 		new Prompt("analyze", "Code analysis template"),
+	 * 		(exchange, request) -> {
+	 * 			String code = request.getArguments().get("code");
+	 * 			return new GetPromptResult(
+	 * 					"Analyze this code:\n\n" + code + "\n\nProvide feedback on:");
+	 * 		})
 	 * }

 	 *
 	 * @param prompt The prompt definition including name and description
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
index 5adda1a74..38f5128e4 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.server.McpServerFeatures.AsyncToolSpecification;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 import io.modelcontextprotocol.util.Assert;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index 41bf0e640..b5841e755 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -30,10 +30,11 @@
 
 /**
  * Test suite for the {@link McpAsyncServer} that can be used with different
- * {@link McpTransportProvider} implementations.
+ * {@link io.modelcontextprotocol.spec.McpServerTransportProvider} implementations.
  *
  * @author Christian Tzolov
  */
+// KEEP IN SYNC with the class in mcp-test module
 public abstract class AbstractMcpAsyncServerTests {
 
 	private static final String TEST_TOOL_NAME = "test-tool";
@@ -101,6 +102,7 @@ void testImmediateClose() {
 			""";
 
 	@Test
+	@Deprecated
 	void testAddTool() {
 		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
 		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
@@ -116,6 +118,23 @@ void testAddTool() {
 	}
 
 	@Test
+	void testAddToolCall() {
+		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(newTool)
+			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.build())).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	@Deprecated
 	void testAddDuplicateTool() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
@@ -136,6 +155,83 @@ void testAddDuplicateTool() {
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 	}
 
+	@Test
+	void testAddDuplicateToolCall() {
+		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+
+		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.build();
+
+		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(duplicateTool)
+			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.build())).verifyErrorSatisfies(error -> {
+				assertThat(error).isInstanceOf(McpError.class)
+					.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
+			});
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testDuplicateToolCallDuringBuilding() {
+		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
+				emptyJsonSchema);
+
+		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) // Duplicate!
+			.build()).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Tool with name 'duplicate-build-toolcall' is already registered.");
+	}
+
+	@Test
+	void testDuplicateToolsInBatchListRegistration() {
+		Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema);
+		List specs = List.of(
+				McpServerFeatures.AsyncToolSpecification.builder()
+					.tool(duplicateTool)
+					.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+					.build(),
+				McpServerFeatures.AsyncToolSpecification.builder()
+					.tool(duplicateTool)
+					.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+					.build() // Duplicate!
+		);
+
+		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(specs)
+			.build()).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Tool with name 'batch-list-tool' is already registered.");
+	}
+
+	@Test
+	void testDuplicateToolsInBatchVarargsRegistration() {
+		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
+
+		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(McpServerFeatures.AsyncToolSpecification.builder()
+				.tool(duplicateTool)
+				.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+				.build(),
+					McpServerFeatures.AsyncToolSpecification.builder()
+						.tool(duplicateTool)
+						.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+						.build() // Duplicate!
+			)
+			.build()).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Tool with name 'batch-varargs-tool' is already registered.");
+	}
+
 	@Test
 	void testRemoveTool() {
 		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
@@ -143,7 +239,7 @@ void testRemoveTool() {
 		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
 			.serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.removeTool(TEST_TOOL_NAME)).verifyComplete();
@@ -172,7 +268,7 @@ void testNotifyToolsListChanged() {
 		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
 			.serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.notifyToolsListChanged()).verifyComplete();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 8a79e3427..208d2e749 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -4,8 +4,16 @@
 
 package io.modelcontextprotocol.server;
 
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
 import java.util.List;
 
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
@@ -17,13 +25,6 @@
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 /**
  * Test suite for the {@link McpSyncServer} that can be used with different
@@ -31,6 +32,7 @@
  *
  * @author Christian Tzolov
  */
+// KEEP IN SYNC with the class in mcp-test module
 public abstract class AbstractMcpSyncServerTests {
 
 	private static final String TEST_TOOL_NAME = "test-tool";
@@ -108,6 +110,7 @@ void testGetAsyncServer() {
 			""";
 
 	@Test
+	@Deprecated
 	void testAddTool() {
 		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
 			.serverInfo("test-server", "1.0.0")
@@ -123,6 +126,23 @@ void testAddTool() {
 	}
 
 	@Test
+	void testAddToolCall() {
+		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
+			.tool(newTool)
+			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.build())).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	@Deprecated
 	void testAddDuplicateTool() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
@@ -140,6 +160,81 @@ void testAddDuplicateTool() {
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
 
+	@Test
+	void testAddDuplicateToolCall() {
+		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+
+		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
+			.build();
+
+		assertThatThrownBy(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
+			.tool(duplicateTool)
+			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.build())).isInstanceOf(McpError.class)
+			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testDuplicateToolCallDuringBuilding() {
+		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
+				emptyJsonSchema);
+
+		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
+			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) // Duplicate!
+			.build()).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Tool with name 'duplicate-build-toolcall' is already registered.");
+	}
+
+	@Test
+	void testDuplicateToolsInBatchListRegistration() {
+		Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema);
+		List specs = List.of(
+				McpServerFeatures.SyncToolSpecification.builder()
+					.tool(duplicateTool)
+					.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+					.build(),
+				McpServerFeatures.SyncToolSpecification.builder()
+					.tool(duplicateTool)
+					.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+					.build() // Duplicate!
+		);
+
+		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(specs)
+			.build()).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Tool with name 'batch-list-tool' is already registered.");
+	}
+
+	@Test
+	void testDuplicateToolsInBatchVarargsRegistration() {
+		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
+
+		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(McpServerFeatures.SyncToolSpecification.builder()
+				.tool(duplicateTool)
+				.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+				.build(),
+					McpServerFeatures.SyncToolSpecification.builder()
+						.tool(duplicateTool)
+						.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+						.build() // Duplicate!
+			)
+			.build()).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Tool with name 'batch-varargs-tool' is already registered.");
+	}
+
 	@Test
 	void testRemoveTool() {
 		Tool tool = new McpSchema.Tool(TEST_TOOL_NAME, "Test tool", emptyJsonSchema);
@@ -147,7 +242,7 @@ void testRemoveTool() {
 		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
 			.serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(tool, (exchange, args) -> new CallToolResult(List.of(), false))
+			.toolCall(tool, (exchange, args) -> new CallToolResult(List.of(), false))
 			.build();
 
 		assertThatCode(() -> mcpSyncServer.removeTool(TEST_TOOL_NAME)).doesNotThrowAnyException();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java b/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
new file mode 100644
index 000000000..6744826c9
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
@@ -0,0 +1,229 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+/**
+ * Tests for {@link McpServerFeatures.AsyncToolSpecification.Builder}.
+ *
+ * @author Christian Tzolov
+ */
+class AsyncToolSpecificationBuilderTest {
+
+	String emptyJsonSchema = """
+			{
+				"type": "object"
+			}
+			""";
+
+	@Test
+	void builderShouldCreateValidAsyncToolSpecification() {
+
+		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+
+		McpServerFeatures.AsyncToolSpecification specification = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(tool)
+			.callHandler((exchange, request) -> Mono
+				.just(new CallToolResult(List.of(new TextContent("Test result")), false)))
+			.build();
+
+		assertThat(specification).isNotNull();
+		assertThat(specification.tool()).isEqualTo(tool);
+		assertThat(specification.callHandler()).isNotNull();
+		assertThat(specification.call()).isNull(); // deprecated field should be null
+	}
+
+	@Test
+	void builderShouldThrowExceptionWhenToolIsNull() {
+		assertThatThrownBy(() -> McpServerFeatures.AsyncToolSpecification.builder()
+			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.build()).isInstanceOf(IllegalArgumentException.class).hasMessage("Tool must not be null");
+	}
+
+	@Test
+	void builderShouldThrowExceptionWhenCallToolIsNull() {
+		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+
+		assertThatThrownBy(() -> McpServerFeatures.AsyncToolSpecification.builder().tool(tool).build())
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Call handler function must not be null");
+	}
+
+	@Test
+	void builderShouldAllowMethodChaining() {
+		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		McpServerFeatures.AsyncToolSpecification.Builder builder = McpServerFeatures.AsyncToolSpecification.builder();
+
+		// Then - verify method chaining returns the same builder instance
+		assertThat(builder.tool(tool)).isSameAs(builder);
+		assertThat(builder.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))))
+			.isSameAs(builder);
+	}
+
+	@Test
+	void builtSpecificationShouldExecuteCallToolCorrectly() {
+		Tool tool = new Tool("calculator", "Simple calculator", emptyJsonSchema);
+		String expectedResult = "42";
+
+		McpServerFeatures.AsyncToolSpecification specification = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(tool)
+			.callHandler((exchange, request) -> {
+				return Mono.just(new CallToolResult(List.of(new TextContent(expectedResult)), false));
+			})
+			.build();
+
+		CallToolRequest request = new CallToolRequest("calculator", Map.of());
+		Mono resultMono = specification.callHandler().apply(null, request);
+
+		StepVerifier.create(resultMono).assertNext(result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.content()).hasSize(1);
+			assertThat(result.content().get(0)).isInstanceOf(TextContent.class);
+			assertThat(((TextContent) result.content().get(0)).text()).isEqualTo(expectedResult);
+			assertThat(result.isError()).isFalse();
+		}).verifyComplete();
+	}
+
+	@Test
+	@SuppressWarnings("deprecation")
+	void deprecatedConstructorShouldWorkCorrectly() {
+		Tool tool = new Tool("deprecated-tool", "A deprecated tool", emptyJsonSchema);
+		String expectedResult = "deprecated result";
+
+		// Test the deprecated constructor that takes a 'call' function
+		McpServerFeatures.AsyncToolSpecification specification = new McpServerFeatures.AsyncToolSpecification(tool,
+				(exchange, arguments) -> Mono
+					.just(new CallToolResult(List.of(new TextContent(expectedResult)), false)));
+
+		assertThat(specification).isNotNull();
+		assertThat(specification.tool()).isEqualTo(tool);
+		assertThat(specification.call()).isNotNull(); // deprecated field should be set
+		assertThat(specification.callHandler()).isNotNull(); // should be automatically
+																// created
+
+		// Test that the callTool function works (it should delegate to the call function)
+		CallToolRequest request = new CallToolRequest("deprecated-tool", Map.of("arg1", "value1"));
+		Mono resultMono = specification.callHandler().apply(null, request);
+
+		StepVerifier.create(resultMono).assertNext(result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.content()).hasSize(1);
+			assertThat(result.content().get(0)).isInstanceOf(TextContent.class);
+			assertThat(((TextContent) result.content().get(0)).text()).isEqualTo(expectedResult);
+			assertThat(result.isError()).isFalse();
+		}).verifyComplete();
+
+		// Test that the deprecated call function also works directly
+		Mono callResultMono = specification.call().apply(null, request.arguments());
+
+		StepVerifier.create(callResultMono).assertNext(result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.content()).hasSize(1);
+			assertThat(result.content().get(0)).isInstanceOf(TextContent.class);
+			assertThat(((TextContent) result.content().get(0)).text()).isEqualTo(expectedResult);
+			assertThat(result.isError()).isFalse();
+		}).verifyComplete();
+	}
+
+	@Test
+	void fromSyncShouldConvertSyncToolSpecificationCorrectly() {
+		Tool tool = new Tool("sync-tool", "A sync tool", emptyJsonSchema);
+		String expectedResult = "sync result";
+
+		// Create a sync tool specification
+		McpServerFeatures.SyncToolSpecification syncSpec = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(tool)
+			.callHandler((exchange, request) -> new CallToolResult(List.of(new TextContent(expectedResult)), false))
+			.build();
+
+		// Convert to async using fromSync
+		McpServerFeatures.AsyncToolSpecification asyncSpec = McpServerFeatures.AsyncToolSpecification
+			.fromSync(syncSpec);
+
+		assertThat(asyncSpec).isNotNull();
+		assertThat(asyncSpec.tool()).isEqualTo(tool);
+		assertThat(asyncSpec.callHandler()).isNotNull();
+		assertThat(asyncSpec.call()).isNull(); // should be null since sync spec doesn't
+												// have deprecated call
+
+		// Test that the converted async specification works correctly
+		CallToolRequest request = new CallToolRequest("sync-tool", Map.of("param", "value"));
+		Mono resultMono = asyncSpec.callHandler().apply(null, request);
+
+		StepVerifier.create(resultMono).assertNext(result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.content()).hasSize(1);
+			assertThat(result.content().get(0)).isInstanceOf(TextContent.class);
+			assertThat(((TextContent) result.content().get(0)).text()).isEqualTo(expectedResult);
+			assertThat(result.isError()).isFalse();
+		}).verifyComplete();
+	}
+
+	@Test
+	@SuppressWarnings("deprecation")
+	void fromSyncShouldConvertSyncToolSpecificationWithDeprecatedCallCorrectly() {
+		Tool tool = new Tool("sync-deprecated-tool", "A sync tool with deprecated call", emptyJsonSchema);
+		String expectedResult = "sync deprecated result";
+		McpAsyncServerExchange nullExchange = null; // Mock or create a suitable exchange
+													// if needed
+
+		// Create a sync tool specification using the deprecated constructor
+		McpServerFeatures.SyncToolSpecification syncSpec = new McpServerFeatures.SyncToolSpecification(tool,
+				(exchange, arguments) -> new CallToolResult(List.of(new TextContent(expectedResult)), false));
+
+		// Convert to async using fromSync
+		McpServerFeatures.AsyncToolSpecification asyncSpec = McpServerFeatures.AsyncToolSpecification
+			.fromSync(syncSpec);
+
+		assertThat(asyncSpec).isNotNull();
+		assertThat(asyncSpec.tool()).isEqualTo(tool);
+		assertThat(asyncSpec.callHandler()).isNotNull();
+		assertThat(asyncSpec.call()).isNotNull(); // should be set since sync spec has
+													// deprecated call
+
+		// Test that the converted async specification works correctly via callTool
+		CallToolRequest request = new CallToolRequest("sync-deprecated-tool", Map.of("param", "value"));
+		Mono resultMono = asyncSpec.callHandler().apply(nullExchange, request);
+
+		StepVerifier.create(resultMono).assertNext(result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.content()).hasSize(1);
+			assertThat(result.content().get(0)).isInstanceOf(TextContent.class);
+			assertThat(((TextContent) result.content().get(0)).text()).isEqualTo(expectedResult);
+			assertThat(result.isError()).isFalse();
+		}).verifyComplete();
+
+		// Test that the deprecated call function also works
+		Mono callResultMono = asyncSpec.call().apply(nullExchange, request.arguments());
+
+		StepVerifier.create(callResultMono).assertNext(result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.content()).hasSize(1);
+			assertThat(result.content().get(0)).isInstanceOf(TextContent.class);
+			assertThat(((TextContent) result.content().get(0)).text()).isEqualTo(expectedResult);
+			assertThat(result.isError()).isFalse();
+		}).verifyComplete();
+	}
+
+	@Test
+	void fromSyncShouldReturnNullWhenSyncSpecIsNull() {
+		assertThat(McpServerFeatures.AsyncToolSpecification.fromSync(null)).isNull();
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/BaseMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/BaseMcpAsyncServerTests.java
deleted file mode 100644
index 208bcb71b..000000000
--- a/mcp/src/test/java/io/modelcontextprotocol/server/BaseMcpAsyncServerTests.java
+++ /dev/null
@@ -1,5 +0,0 @@
-package io.modelcontextprotocol.server;
-
-public abstract class BaseMcpAsyncServerTests {
-
-}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java b/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
new file mode 100644
index 000000000..4aac46952
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
@@ -0,0 +1,98 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+
+/**
+ * Tests for {@link McpServerFeatures.SyncToolSpecification.Builder}.
+ *
+ * @author Christian Tzolov
+ */
+class SyncToolSpecificationBuilderTest {
+
+	String emptyJsonSchema = """
+			{
+				"type": "object"
+			}
+			""";
+
+	@Test
+	void builderShouldCreateValidSyncToolSpecification() {
+
+		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+
+		McpServerFeatures.SyncToolSpecification specification = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(tool)
+			.callHandler((exchange, request) -> new CallToolResult(List.of(new TextContent("Test result")), false))
+			.build();
+
+		assertThat(specification).isNotNull();
+		assertThat(specification.tool()).isEqualTo(tool);
+		assertThat(specification.callHandler()).isNotNull();
+		assertThat(specification.call()).isNull(); // deprecated field should be null
+	}
+
+	@Test
+	void builderShouldThrowExceptionWhenToolIsNull() {
+		assertThatThrownBy(() -> McpServerFeatures.SyncToolSpecification.builder()
+			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.build()).isInstanceOf(IllegalArgumentException.class).hasMessage("Tool must not be null");
+	}
+
+	@Test
+	void builderShouldThrowExceptionWhenCallToolIsNull() {
+		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+
+		assertThatThrownBy(() -> McpServerFeatures.SyncToolSpecification.builder().tool(tool).build())
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("CallTool function must not be null");
+	}
+
+	@Test
+	void builderShouldAllowMethodChaining() {
+		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		McpServerFeatures.SyncToolSpecification.Builder builder = McpServerFeatures.SyncToolSpecification.builder();
+
+		// Then - verify method chaining returns the same builder instance
+		assertThat(builder.tool(tool)).isSameAs(builder);
+		assertThat(builder.callHandler((exchange, request) -> new CallToolResult(List.of(), false))).isSameAs(builder);
+	}
+
+	@Test
+	void builtSpecificationShouldExecuteCallToolCorrectly() {
+		Tool tool = new Tool("calculator", "Simple calculator", emptyJsonSchema);
+		String expectedResult = "42";
+
+		McpServerFeatures.SyncToolSpecification specification = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(tool)
+			.callHandler((exchange, request) -> {
+				// Simple test implementation
+				return new CallToolResult(List.of(new TextContent(expectedResult)), false);
+			})
+			.build();
+
+		CallToolRequest request = new CallToolRequest("calculator", Map.of());
+		CallToolResult result = specification.callHandler().apply(null, request);
+
+		assertThat(result).isNotNull();
+		assertThat(result.content()).hasSize(1);
+		assertThat(result.content().get(0)).isInstanceOf(TextContent.class);
+		assertThat(((TextContent) result.content().get(0)).text()).isEqualTo(expectedResult);
+		assertThat(result.isError()).isFalse();
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
index dcc7917d0..ac10df4f5 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
@@ -109,13 +109,15 @@ public void after() {
 	// @Disabled
 	void testCreateMessageWithoutSamplingCapabilities() {
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
 
-					exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
+				exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
 
-					return Mono.just(mock(CallToolResult.class));
-				});
+				return Mono.just(mock(CallToolResult.class));
+			})
+			.build();
 
 		var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build();
 
@@ -151,31 +153,33 @@ void testCreateMessageSuccess() {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
-
-					var createMessageRequest = McpSchema.CreateMessageRequest.builder()
-						.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-								new McpSchema.TextContent("Test message"))))
-						.modelPreferences(ModelPreferences.builder()
-							.hints(List.of())
-							.costPriority(1.0)
-							.speedPriority(1.0)
-							.intelligencePriority(1.0)
-							.build())
-						.build();
-
-					StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-						assertThat(result).isNotNull();
-						assertThat(result.role()).isEqualTo(Role.USER);
-						assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-						assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-						assertThat(result.model()).isEqualTo("MockModelName");
-						assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-					}).verifyComplete();
-
-					return Mono.just(callResponse);
-				});
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
 
 		var mcpServer = McpServer.async(mcpServerTransportProvider)
 			.serverInfo("test-server", "1.0.0")
@@ -226,31 +230,33 @@ void testCreateMessageWithRequestTimeoutSuccess() throws InterruptedException {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
-
-					var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-						.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-								new McpSchema.TextContent("Test message"))))
-						.modelPreferences(ModelPreferences.builder()
-							.hints(List.of())
-							.costPriority(1.0)
-							.speedPriority(1.0)
-							.intelligencePriority(1.0)
-							.build())
-						.build();
-
-					StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
-						assertThat(result).isNotNull();
-						assertThat(result.role()).isEqualTo(Role.USER);
-						assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-						assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-						assertThat(result.model()).isEqualTo("MockModelName");
-						assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-					}).verifyComplete();
-
-					return Mono.just(callResponse);
-				});
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
 
 		var mcpServer = McpServer.async(mcpServerTransportProvider)
 			.serverInfo("test-server", "1.0.0")
@@ -298,31 +304,33 @@ void testCreateMessageWithRequestTimeoutFail() throws InterruptedException {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
-
-					var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-						.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-								new McpSchema.TextContent("Test message"))))
-						.modelPreferences(ModelPreferences.builder()
-							.hints(List.of())
-							.costPriority(1.0)
-							.speedPriority(1.0)
-							.intelligencePriority(1.0)
-							.build())
-						.build();
-
-					StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
-						assertThat(result).isNotNull();
-						assertThat(result.role()).isEqualTo(Role.USER);
-						assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-						assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-						assertThat(result.model()).isEqualTo("MockModelName");
-						assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-					}).verifyComplete();
-
-					return Mono.just(callResponse);
-				});
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
 
 		var mcpServer = McpServer.async(mcpServerTransportProvider)
 			.serverInfo("test-server", "1.0.0")
@@ -348,13 +356,15 @@ void testCreateMessageWithRequestTimeoutFail() throws InterruptedException {
 	// @Disabled
 	void testCreateElicitationWithoutElicitationCapabilities() {
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
 
-					exchange.createElicitation(mock(ElicitRequest.class)).block();
+				exchange.createElicitation(mock(ElicitRequest.class)).block();
 
-					return Mono.just(mock(CallToolResult.class));
-				});
+				return Mono.just(mock(CallToolResult.class));
+			})
+			.build();
 
 		var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build();
 
@@ -388,23 +398,25 @@ void testCreateElicitationSuccess() {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
 
-					var elicitationRequest = ElicitRequest.builder()
-						.message("Test message")
-						.requestedSchema(
-								Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-						.build();
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
 
-					StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-						assertThat(result).isNotNull();
-						assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-						assertThat(result.content().get("message")).isEqualTo("Test message");
-					}).verifyComplete();
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
 
-					return Mono.just(callResponse);
-				});
+				return Mono.just(callResponse);
+			})
+			.build();
 
 		var mcpServer = McpServer.async(mcpServerTransportProvider)
 			.serverInfo("test-server", "1.0.0")
@@ -454,23 +466,25 @@ void testCreateElicitationWithRequestTimeoutSuccess() {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
 
-					var elicitationRequest = ElicitRequest.builder()
-						.message("Test message")
-						.requestedSchema(
-								Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-						.build();
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
 
-					StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-						assertThat(result).isNotNull();
-						assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-						assertThat(result.content().get("message")).isEqualTo("Test message");
-					}).verifyComplete();
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
 
-					return Mono.just(callResponse);
-				});
+				return Mono.just(callResponse);
+			})
+			.build();
 
 		var mcpServer = McpServer.async(mcpServerTransportProvider)
 			.serverInfo("test-server", "1.0.0")
@@ -517,23 +531,25 @@ void testCreateElicitationWithRequestTimeoutFail() {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
 
-					var elicitationRequest = ElicitRequest.builder()
-						.message("Test message")
-						.requestedSchema(
-								Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-						.build();
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
 
-					StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-						assertThat(result).isNotNull();
-						assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-						assertThat(result.content().get("message")).isEqualTo("Test message");
-					}).verifyComplete();
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
 
-					return Mono.just(callResponse);
-				});
+				return Mono.just(callResponse);
+			})
+			.build();
 
 		var mcpServer = McpServer.async(mcpServerTransportProvider)
 			.serverInfo("test-server", "1.0.0")
@@ -602,13 +618,15 @@ void testRootsSuccess() {
 	@Test
 	void testRootsWithoutCapability() {
 
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
 
-					exchange.listRoots(); // try to list roots
+				exchange.listRoots(); // try to list roots
 
-					return mock(CallToolResult.class);
-				});
+				return mock(CallToolResult.class);
+			})
+			.build();
 
 		var mcpServer = McpServer.sync(mcpServerTransportProvider).rootsChangeHandler((exchange, rootsUpdate) -> {
 		}).tools(tool).build();
@@ -726,20 +744,22 @@ void testRootsServerCloseWithActiveSubscription() {
 	void testToolCallSuccess() {
 
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
-					assertThat(McpTestServletFilter.getThreadLocalValue())
-						.as("blocking code exectuion should be offloaded")
-						.isNull();
-					// perform a blocking call to a remote service
-					String response = RestClient.create()
-						.get()
-						.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-						.retrieve()
-						.body(String.class);
-					assertThat(response).isNotBlank();
-					return callResponse;
-				});
+
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+				assertThat(McpTestServletFilter.getThreadLocalValue()).as("blocking code exectuion should be offloaded")
+					.isNull();
+				// perform a blocking call to a remote service
+				String response = RestClient.create()
+					.get()
+					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
+					.retrieve()
+					.body(String.class);
+				assertThat(response).isNotBlank();
+				return callResponse;
+			})
+			.build();
 
 		var mcpServer = McpServer.sync(mcpServerTransportProvider)
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -796,17 +816,19 @@ void testToolCallImmediateExecution() {
 	void testToolListChangeHandlingSuccess() {
 
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
-					// perform a blocking call to a remote service
-					String response = RestClient.create()
-						.get()
-						.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-						.retrieve()
-						.body(String.class);
-					assertThat(response).isNotBlank();
-					return callResponse;
-				});
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+				// perform a blocking call to a remote service
+				String response = RestClient.create()
+					.get()
+					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
+					.retrieve()
+					.body(String.class);
+				assertThat(response).isNotBlank();
+				return callResponse;
+			})
+			.build();
 
 		AtomicReference> rootsRef = new AtomicReference<>();
 
@@ -847,9 +869,10 @@ void testToolListChangeHandlingSuccess() {
 			});
 
 			// Add a new tool
-			McpServerFeatures.SyncToolSpecification tool2 = new McpServerFeatures.SyncToolSpecification(
-					new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema),
-					(exchange, request) -> callResponse);
+			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
+				.tool(new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema))
+				.callHandler((exchange, request) -> callResponse)
+				.build();
 
 			mcpServer.addTool(tool2);
 
@@ -883,59 +906,60 @@ void testLoggingNotification() {
 		List receivedNotifications = new ArrayList<>();
 
 		// Create server with a tool that sends logging notifications
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema),
-				(exchange, request) -> {
-
-					// Create and send notifications with different levels
-
-					// This should be filtered out (DEBUG < NOTICE)
-					exchange
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-							.level(McpSchema.LoggingLevel.DEBUG)
-							.logger("test-logger")
-							.data("Debug message")
-							.build())
-						.block();
-
-					// This should be sent (NOTICE >= NOTICE)
-					exchange
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-							.level(McpSchema.LoggingLevel.NOTICE)
-							.logger("test-logger")
-							.data("Notice message")
-							.build())
-						.block();
-
-					// This should be sent (ERROR > NOTICE)
-					exchange
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-							.level(McpSchema.LoggingLevel.ERROR)
-							.logger("test-logger")
-							.data("Error message")
-							.build())
-						.block();
-
-					// This should be filtered out (INFO < NOTICE)
-					exchange
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-							.level(McpSchema.LoggingLevel.INFO)
-							.logger("test-logger")
-							.data("Another info message")
-							.build())
-						.block();
-
-					// This should be sent (ERROR >= NOTICE)
-					exchange
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-							.level(McpSchema.LoggingLevel.ERROR)
-							.logger("test-logger")
-							.data("Another error message")
-							.build())
-						.block();
-
-					return Mono.just(new CallToolResult("Logging test completed", false));
-				});
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications with different levels
+
+				// This should be filtered out (DEBUG < NOTICE)
+				exchange
+					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+						.level(McpSchema.LoggingLevel.DEBUG)
+						.logger("test-logger")
+						.data("Debug message")
+						.build())
+					.block();
+
+				// This should be sent (NOTICE >= NOTICE)
+				exchange
+					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+						.level(McpSchema.LoggingLevel.NOTICE)
+						.logger("test-logger")
+						.data("Notice message")
+						.build())
+					.block();
+
+				// This should be sent (ERROR > NOTICE)
+				exchange
+					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+						.level(McpSchema.LoggingLevel.ERROR)
+						.logger("test-logger")
+						.data("Error message")
+						.build())
+					.block();
+
+				// This should be filtered out (INFO < NOTICE)
+				exchange
+					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+						.level(McpSchema.LoggingLevel.INFO)
+						.logger("test-logger")
+						.data("Another info message")
+						.build())
+					.block();
+
+				// This should be sent (ERROR >= NOTICE)
+				exchange
+					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+						.level(McpSchema.LoggingLevel.ERROR)
+						.logger("test-logger")
+						.data("Another error message")
+						.build())
+					.block();
+
+				return Mono.just(new CallToolResult("Logging test completed", false));
+			})
+			.build();
 
 		var mcpServer = McpServer.async(mcpServerTransportProvider)
 			.serverInfo("test-server", "1.0.0")

From c8c08dd1a6524768fc326c1cb486e7b27fc9156a Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Fri, 11 Jul 2025 13:45:37 +0200
Subject: [PATCH 006/125] Add legacy constructors for backwards compatibility
 in McpSchema record types

  As a followup of #372 introduce new constructors to several record types
  in McpSchema (Resource, ResourceTemplate, Prompt, PromptArgument, Tool,
  PromptReference, and ResourceLink) to improve backwards compatibility
  with previous code versions.

Signed-off-by: Christian Tzolov 
---
 .../modelcontextprotocol/spec/McpSchema.java  | 77 +++++++++++++++----
 1 file changed, 62 insertions(+), 15 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 79534c87c..3a4b53da2 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -578,6 +578,16 @@ public record Resource( // @formatter:off
 				@JsonProperty("size") Long size,
 				@JsonProperty("annotations") Annotations annotations) implements Annotated, ResourceContent {// @formatter:on
 
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link Resource#builder()} instead.
+		 */
+		@Deprecated
+		public Resource(String uri, String name, String description, String mimeType, Long size,
+				Annotations annotations) {
+			this(uri, name, null, description, mimeType, null, annotations);
+		}
+
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link Resource#builder()} instead.
@@ -677,8 +687,13 @@ public record ResourceTemplate( // @formatter:off
 				@JsonProperty("title") String title,
 				@JsonProperty("description") String description,
 				@JsonProperty("mimeType") String mimeType,
-				@JsonProperty("annotations") Annotations annotations) implements Annotated, BaseMetadata {
-		} // @formatter:on
+				@JsonProperty("annotations") Annotations annotations) implements Annotated, BaseMetadata {// @formatter:on
+
+		public ResourceTemplate(String uriTemplate, String name, String description, String mimeType,
+				Annotations annotations) {
+			this(uriTemplate, name, null, description, mimeType, annotations);
+		}
+	}
 
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -802,8 +817,12 @@ public record Prompt( // @formatter:off
 				@JsonProperty("name") String name,
 				@JsonProperty("title") String title,
 				@JsonProperty("description") String description,
-				@JsonProperty("arguments") List arguments) implements BaseMetadata {
-		} // @formatter:on
+				@JsonProperty("arguments") List arguments) implements BaseMetadata { // @formatter:on
+
+		public Prompt(String name, String description, List arguments) {
+			this(name, null, description, arguments != null ? arguments : new ArrayList<>());
+		}
+	}
 
 	/**
 	 * Describes an argument that a prompt can accept.
@@ -819,8 +838,12 @@ public record PromptArgument( // @formatter:off
 				@JsonProperty("name") String name,
 				@JsonProperty("title") String title,
 				@JsonProperty("description") String description,
-				@JsonProperty("required") Boolean required) implements BaseMetadata {
-		}// @formatter:on
+				@JsonProperty("required") Boolean required) implements BaseMetadata {// @formatter:on
+
+		public PromptArgument(String name, String description, Boolean required) {
+			this(name, null, description, required);
+		}
+	}
 
 	/**
 	 * Describes a message returned as part of a prompt.
@@ -946,6 +969,15 @@ public record Tool( // @formatter:off
 				@JsonProperty("inputSchema") JsonSchema inputSchema,
 				@JsonProperty("annotations") ToolAnnotations annotations) implements BaseMetadata { // @formatter:on
 
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link Tool#builder()} instead.
+		 */
+		@Deprecated
+		public Tool(String name, String description, JsonSchema inputSchema, ToolAnnotations annotations) {
+			this(name, null, description, inputSchema, annotations);
+		}
+
 		public Tool(String name, String description, String schema) {
 			this(name, null, description, parseSchema(schema), null);
 		}
@@ -1688,17 +1720,21 @@ public sealed interface CompleteReference permits PromptReference, ResourceRefer
 	public record PromptReference(// @formatter:off
 				@JsonProperty("type") String type,
 				@JsonProperty("name") String name,
-				@JsonProperty("title") String title ) implements McpSchema.CompleteReference, BaseMetadata {
+				@JsonProperty("title") String title ) implements McpSchema.CompleteReference, BaseMetadata { // @formatter:on
 
-				public PromptReference(String name) {
-						this("ref/prompt", name, null);
-				}
+		public PromptReference(String type, String name) {
+			this(type, name, null);
+		}
 
-				@Override
-				public String identifier() {
-						return name();
-				}
-		}// @formatter:on
+		public PromptReference(String name) {
+			this("ref/prompt", name, null);
+		}
+
+		@Override
+		public String identifier() {
+			return name();
+		}
+	}
 
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -1911,6 +1947,17 @@ public record ResourceLink( // @formatter:off
 				@JsonProperty("size") Long size,
 				@JsonProperty("annotations") Annotations annotations) implements Annotated, Content, ResourceContent { // @formatter:on
 
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link ResourceLink#ResourceLink(String, String, String, String, String, Long, Annotations)}
+		 * instead.
+		 */
+		@Deprecated
+		public ResourceLink(String name, String uri, String description, String mimeType, Long size,
+				Annotations annotations) {
+			this(name, null, uri, description, mimeType, size, annotations);
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}

From dc477fc522b1e71b2a52d1e06f5f5fa5a93bb3ae Mon Sep 17 00:00:00 2001
From: bzsurbhi 
Date: Wed, 2 Jul 2025 13:31:18 -0700
Subject: [PATCH 007/125] feat: add context support to CompleteRequest for
 dependent completions

- Add CompleteContext record to support contextual completion scenarios
- Update CompleteRequest to include context and meta fields with backward-compatible constructors
- Modify McpAsyncServer to extract and pass context/meta from request parameters
- Add tests for context-aware completions including dependent scenarios
- Maintain backward compatibility for existing completion handlers

Signed-off-by: Christian Tzolov 
---
 .../server/McpAsyncServer.java                |  10 +-
 .../modelcontextprotocol/spec/McpSchema.java  |  33 +-
 .../server/McpCompletionTests.java            | 303 ++++++++++++++++++
 .../spec/McpSchemaTests.java                  |   2 +-
 4 files changed, 336 insertions(+), 12 deletions(-)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java

diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index 5c8423b6d..b06af9e85 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -721,6 +721,8 @@ private McpSchema.CompleteRequest parseCompletionParams(Object object) {
 		Map params = (Map) object;
 		Map refMap = (Map) params.get("ref");
 		Map argMap = (Map) params.get("argument");
+		Map contextMap = (Map) params.get("context");
+		Map meta = (Map) params.get("_meta");
 
 		String refType = (String) refMap.get("type");
 
@@ -736,7 +738,13 @@ private McpSchema.CompleteRequest parseCompletionParams(Object object) {
 		McpSchema.CompleteRequest.CompleteArgument argument = new McpSchema.CompleteRequest.CompleteArgument(argName,
 				argValue);
 
-		return new McpSchema.CompleteRequest(ref, argument);
+		McpSchema.CompleteRequest.CompleteContext context = null;
+		if (contextMap != null) {
+			Map arguments = (Map) contextMap.get("arguments");
+			context = new McpSchema.CompleteRequest.CompleteContext(arguments);
+		}
+
+		return new McpSchema.CompleteRequest(ref, argument, meta, context);
 	}
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 3a4b53da2..acdc18e10 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -1755,18 +1755,31 @@ public String identifier() {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record CompleteRequest(// @formatter:off
-				@JsonProperty("ref") McpSchema.CompleteReference ref,
-				@JsonProperty("argument") CompleteArgument argument,
-				@JsonProperty("_meta") Map meta) implements Request {
+		@JsonProperty("ref") McpSchema.CompleteReference ref,
+		@JsonProperty("argument") CompleteArgument argument,
+		@JsonProperty("_meta") Map meta,
+		@JsonProperty("context") CompleteContext context) implements Request {
 
-				public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument) {
-						this(ref, argument, null);
-				}
+		public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument, Map meta) {
+			this(ref, argument, meta, null);
+		}
 
-				public record CompleteArgument(
-						@JsonProperty("name") String name,
-						@JsonProperty("value") String value) {
-				}// @formatter:on
+		public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument, CompleteContext context) {
+			this(ref, argument, null, context);
+		}
+
+		public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument) {
+			this(ref, argument, null, null);
+		}
+		
+		public record CompleteArgument(
+			@JsonProperty("name") String name,
+			@JsonProperty("value") String value) {
+		}
+
+		public record CompleteContext(
+			@JsonProperty("arguments") Map arguments) {
+		}// @formatter:on
 	}
 
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
new file mode 100644
index 000000000..26b75946b
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
@@ -0,0 +1,303 @@
+package io.modelcontextprotocol.server;
+
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
+
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import static org.assertj.core.api.Assertions.assertThat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.Prompt;
+import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
+import io.modelcontextprotocol.spec.McpSchema.ReadResourceResult;
+import io.modelcontextprotocol.spec.McpSchema.ResourceReference;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpError;
+
+/**
+ * Tests for completion functionality with context support.
+ *
+ * @author Surbhi Bansal
+ */
+class McpCompletionTests {
+
+	private HttpServletSseServerTransportProvider mcpServerTransportProvider;
+
+	private static final String CUSTOM_MESSAGE_ENDPOINT = "/otherPath/mcp/message";
+
+	McpClient.SyncSpec clientBuilder;
+
+	private Tomcat tomcat;
+
+	@BeforeEach
+	public void before() {
+		// Create and con figure the transport provider
+		mcpServerTransportProvider = HttpServletSseServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
+			.build();
+
+		tomcat = TomcatTestUtil.createTomcatServer("", 3400, mcpServerTransportProvider);
+		try {
+			tomcat.start();
+			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		this.clientBuilder = McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + 3400).build());
+	}
+
+	@AfterEach
+	public void after() {
+		if (mcpServerTransportProvider != null) {
+			mcpServerTransportProvider.closeGracefully().block();
+		}
+		if (tomcat != null) {
+			try {
+				tomcat.stop();
+				tomcat.destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	@Test
+	void testCompletionHandlerReceivesContext() {
+		AtomicReference receivedRequest = new AtomicReference<>();
+		BiFunction completionHandler = (exchange, request) -> {
+			receivedRequest.set(request);
+			return new CompleteResult(new CompleteResult.CompleteCompletion(List.of("test-completion"), 1, false));
+		};
+
+		ResourceReference resourceRef = new ResourceReference("ref/resource", "test://resource/{param}");
+
+		McpSchema.Resource resource = new McpSchema.Resource("test://resource/{param}", "Test Resource",
+				"A resource for testing", "text/plain", 123L, null);
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().completions().build())
+			.resources(new McpServerFeatures.SyncResourceSpecification(resource,
+					(exchange, req) -> new ReadResourceResult(List.of())))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(resourceRef, completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+			.build();) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Test with context
+			CompleteRequest request = new CompleteRequest(resourceRef,
+					new CompleteRequest.CompleteArgument("param", "test"), null,
+					new CompleteRequest.CompleteContext(Map.of("previous", "value")));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			// Verify handler received the context
+			assertThat(receivedRequest.get().context()).isNotNull();
+			assertThat(receivedRequest.get().context().arguments()).containsEntry("previous", "value");
+			assertThat(result.completion().values()).containsExactly("test-completion");
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testCompletionBackwardCompatibility() {
+		AtomicReference contextWasNull = new AtomicReference<>(false);
+		BiFunction completionHandler = (exchange, request) -> {
+			contextWasNull.set(request.context() == null);
+			return new CompleteResult(
+					new CompleteResult.CompleteCompletion(List.of("no-context-completion"), 1, false));
+		};
+
+		McpSchema.Prompt prompt = new Prompt("test-prompt", "this is a test prompt",
+				List.of(new PromptArgument("arg", "string", false)));
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().completions().build())
+			.prompts(new McpServerFeatures.SyncPromptSpecification(prompt,
+					(mcpSyncServerExchange, getPromptRequest) -> null))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(
+					new PromptReference("ref/prompt", "test-prompt"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+			.build();) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Test without context
+			CompleteRequest request = new CompleteRequest(new PromptReference("ref/prompt", "test-prompt"),
+					new CompleteRequest.CompleteArgument("arg", "val"));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			// Verify context was null
+			assertThat(contextWasNull.get()).isTrue();
+			assertThat(result.completion().values()).containsExactly("no-context-completion");
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testDependentCompletionScenario() {
+		BiFunction completionHandler = (exchange, request) -> {
+			// Simulate database/table completion scenario
+			if (request.ref() instanceof ResourceReference resourceRef) {
+				if ("db://{database}/{table}".equals(resourceRef.uri())) {
+					if ("database".equals(request.argument().name())) {
+						// Complete database names
+						return new CompleteResult(new CompleteResult.CompleteCompletion(
+								List.of("users_db", "products_db", "analytics_db"), 3, false));
+					}
+					else if ("table".equals(request.argument().name())) {
+						// Complete table names based on selected database
+						if (request.context() != null && request.context().arguments() != null) {
+							String db = request.context().arguments().get("database");
+							if ("users_db".equals(db)) {
+								return new CompleteResult(new CompleteResult.CompleteCompletion(
+										List.of("users", "sessions", "permissions"), 3, false));
+							}
+							else if ("products_db".equals(db)) {
+								return new CompleteResult(new CompleteResult.CompleteCompletion(
+										List.of("products", "categories", "inventory"), 3, false));
+							}
+						}
+					}
+				}
+			}
+			return new CompleteResult(new CompleteResult.CompleteCompletion(List.of(), 0, false));
+		};
+
+		McpSchema.Resource resource = new McpSchema.Resource("db://{database}/{table}", "Database Table",
+				"Resource representing a table in a database", "application/json", 456L, null);
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().completions().build())
+			.resources(new McpServerFeatures.SyncResourceSpecification(resource,
+					(exchange, req) -> new ReadResourceResult(List.of())))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(
+					new ResourceReference("ref/resource", "db://{database}/{table}"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+			.build();) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// First, complete database
+			CompleteRequest dbRequest = new CompleteRequest(
+					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new CompleteRequest.CompleteArgument("database", ""));
+
+			CompleteResult dbResult = mcpClient.completeCompletion(dbRequest);
+			assertThat(dbResult.completion().values()).contains("users_db", "products_db");
+
+			// Then complete table with database context
+			CompleteRequest tableRequest = new CompleteRequest(
+					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new CompleteRequest.CompleteArgument("table", ""),
+					new CompleteRequest.CompleteContext(Map.of("database", "users_db")));
+
+			CompleteResult tableResult = mcpClient.completeCompletion(tableRequest);
+			assertThat(tableResult.completion().values()).containsExactly("users", "sessions", "permissions");
+
+			// Different database gives different tables
+			CompleteRequest tableRequest2 = new CompleteRequest(
+					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new CompleteRequest.CompleteArgument("table", ""),
+					new CompleteRequest.CompleteContext(Map.of("database", "products_db")));
+
+			CompleteResult tableResult2 = mcpClient.completeCompletion(tableRequest2);
+			assertThat(tableResult2.completion().values()).containsExactly("products", "categories", "inventory");
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testCompletionErrorOnMissingContext() {
+		BiFunction completionHandler = (exchange, request) -> {
+			if (request.ref() instanceof ResourceReference resourceRef) {
+				if ("db://{database}/{table}".equals(resourceRef.uri())) {
+					if ("table".equals(request.argument().name())) {
+						// Check if database context is provided
+						if (request.context() == null || request.context().arguments() == null
+								|| !request.context().arguments().containsKey("database")) {
+							throw new McpError("Please select a database first to see available tables");
+						}
+						// Normal completion if context is provided
+						String db = request.context().arguments().get("database");
+						if ("test_db".equals(db)) {
+							return new CompleteResult(new CompleteResult.CompleteCompletion(
+									List.of("users", "orders", "products"), 3, false));
+						}
+					}
+				}
+			}
+			return new CompleteResult(new CompleteResult.CompleteCompletion(List.of(), 0, false));
+		};
+
+		McpSchema.Resource resource = new McpSchema.Resource("db://{database}/{table}", "Database Table",
+				"Resource representing a table in a database", "application/json", 456L, null);
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().completions().build())
+			.resources(new McpServerFeatures.SyncResourceSpecification(resource,
+					(exchange, req) -> new ReadResourceResult(List.of())))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(
+					new ResourceReference("ref/resource", "db://{database}/{table}"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample" + "client", "0.0.0"))
+			.build();) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Try to complete table without database context - should raise error
+			CompleteRequest requestWithoutContext = new CompleteRequest(
+					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new CompleteRequest.CompleteArgument("table", ""));
+
+			assertThatExceptionOfType(McpError.class)
+				.isThrownBy(() -> mcpClient.completeCompletion(requestWithoutContext))
+				.withMessageContaining("Please select a database first");
+
+			// Now complete with proper context - should work normally
+			CompleteRequest requestWithContext = new CompleteRequest(
+					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new CompleteRequest.CompleteArgument("table", ""),
+					new CompleteRequest.CompleteContext(Map.of("database", "test_db")));
+
+			CompleteResult resultWithContext = mcpClient.completeCompletion(requestWithContext);
+			assertThat(resultWithContext.completion().values()).containsExactly("users", "orders", "products");
+		}
+
+		mcpServer.close();
+	}
+
+}
\ No newline at end of file
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index 786be3294..1d0ba302b 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -1266,7 +1266,7 @@ void testCompleteRequestWithMeta() throws Exception {
 		Map meta = new HashMap<>();
 		meta.put("progressToken", "complete-progress-789");
 
-		McpSchema.CompleteRequest request = new McpSchema.CompleteRequest(resourceRef, argument, meta);
+		McpSchema.CompleteRequest request = new McpSchema.CompleteRequest(resourceRef, argument, meta, null);
 
 		String value = mapper.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)

From d282d40a38a1453ac130c43eb6ca6262f5f8745a Mon Sep 17 00:00:00 2001
From: Sun Yuhan 
Date: Thu, 10 Jul 2025 20:14:43 +0800
Subject: [PATCH 008/125] refactor: replace string concatenation with {}
 placeholders in log statements

Signed-off-by: Sun Yuhan 
---
 .../client/transport/StdioClientTransport.java                | 4 ++--
 .../io/modelcontextprotocol/spec/McpClientSessionTests.java   | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
index 5553445b6..009d415e0 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
@@ -269,7 +269,7 @@ private void startInboundProcessing() {
 					}
 					catch (Exception e) {
 						if (!isClosing) {
-							logger.error("Error processing inbound message for line: " + line, e);
+							logger.error("Error processing inbound message for line: {}", line, e);
 						}
 						break;
 					}
@@ -366,7 +366,7 @@ public Mono closeGracefully() {
 			}
 		})).doOnNext(process -> {
 			if (process.exitValue() != 0) {
-				logger.warn("Process terminated with code " + process.exitValue());
+				logger.warn("Process terminated with code {}", process.exitValue());
 			}
 			else {
 				logger.info("MCP server process stopped");
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
index f72be43e0..85dcd26c2 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
@@ -47,7 +47,7 @@ class McpClientSessionTests {
 	void setUp() {
 		transport = new MockMcpClientTransport();
 		session = new McpClientSession(TIMEOUT, transport, Map.of(),
-				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: " + params))));
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))));
 	}
 
 	@AfterEach

From b678de65141b64fa0f007b0077bc7f6e9feb57ee Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Sun, 13 Jul 2025 10:47:33 +0200
Subject: [PATCH 009/125] fix: improve error handling in
 HttpClientSseClientTransport and add test

- Include response body in error messages for better debugging
- Change sendHttpPost return type from HttpResponse to HttpResponse
- Use BodyHandlers.ofString() instead of discarding response body
- Add testErrorOnBogusMessage test to verify error handling for invalid JSON-RPC messages
- Test validates that malformed messages return 400 status with descriptive error message

Replace #361

Signed-off-by: Christian Tzolov 

Co-authored-by: jkma 
---
 .../client/transport/HttpClientSseClientTransport.java |  8 ++++----
 .../transport/HttpClientSseClientTransportTests.java   | 10 ++++++++++
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 271f38231..8598e3164 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -424,8 +424,8 @@ public Mono sendMessage(JSONRPCMessage message) {
 				.flatMap(body -> sendHttpPost(messageEndpointUri, body).handle((response, sink) -> {
 					if (response.statusCode() != 200 && response.statusCode() != 201 && response.statusCode() != 202
 							&& response.statusCode() != 206) {
-						sink.error(new RuntimeException(
-								"Sending message failed with a non-OK HTTP code: " + response.statusCode()));
+						sink.error(new RuntimeException("Sending message failed with a non-OK HTTP code: "
+								+ response.statusCode() + " - " + response.body()));
 					}
 					else {
 						sink.next(response);
@@ -453,7 +453,7 @@ private Mono serializeMessage(final JSONRPCMessage message) {
 		});
 	}
 
-	private Mono> sendHttpPost(final String endpoint, final String body) {
+	private Mono> sendHttpPost(final String endpoint, final String body) {
 		final URI requestUri = Utils.resolveUri(baseUri, endpoint);
 		final HttpRequest request = this.requestBuilder.copy()
 			.uri(requestUri)
@@ -461,7 +461,7 @@ private Mono> sendHttpPost(final String endpoint, final Strin
 			.build();
 
 		// TODO: why discard the body?
-		return Mono.fromFuture(httpClient.sendAsync(request, HttpResponse.BodyHandlers.discarding()));
+		return Mono.fromFuture(httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString()));
 	}
 
 	/**
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
index 3f1b71e63..31430543a 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
@@ -105,6 +105,16 @@ void cleanup() {
 		container.stop();
 	}
 
+	@Test
+	void testErrorOnBogusMessage() {
+		// bogus message
+		JSONRPCRequest bogusMessage = new JSONRPCRequest(null, null, "test-id", Map.of("key", "value"));
+
+		StepVerifier.create(transport.sendMessage(bogusMessage))
+			.verifyErrorMessage(
+					"Sending message failed with a non-OK HTTP code: 400 - Invalid message: {\"id\":\"test-id\",\"params\":{\"key\":\"value\"}}");
+	}
+
 	@Test
 	void testMessageProcessing() {
 		// Create a test message

From 8a2f97f1b1995880c492159dd1b4c50266d0b579 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Mon, 30 Jun 2025 14:08:50 +0200
Subject: [PATCH 010/125] feat: add structured output support for MCP tools
 (#357)

- Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation
 - put the JsonSchemaValidator classes into a dedicated spec package
 - add schema caching to DefaultJsonSchemaValidator for better performance
- Extend Tool schema to support outputSchema field for defining expected output structure
- Add structuredContent field to CallToolResult for validated structured responses
- Implement automatic validation of tool outputs against their defined schemas
- Add comprehensive test coverage for structured output validation scenarios
- Add json-schema-validator and json-unit-assertj dependencies for validation and testing
- Update McpServer builders to accept custom JsonSchemaValidator instances
- Ensure backward compatibility with existing tools without output schemas

This implements the MCP specification requirement that tools with output schemas
must provide structured results conforming to those schemas, with automatic
validation and error handling for non-conforming outputs.
https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content

Signed-off-by: Christian Tzolov 
---
 mcp-spring/mcp-spring-webflux/pom.xml         |   7 +
 .../WebFluxSseIntegrationTests.java           | 260 +++++++
 mcp-spring/mcp-spring-webmvc/pom.xml          |   9 +-
 .../server/WebMvcSseIntegrationTests.java     | 269 ++++++-
 mcp/pom.xml                                   |  25 +-
 .../server/McpAsyncServer.java                | 128 +++-
 .../server/McpServer.java                     |  36 +-
 .../spec/DefaultJsonSchemaValidator.java      | 169 +++++
 .../spec/JsonSchemaValidator.java             |  44 ++
 .../modelcontextprotocol/spec/McpSchema.java  | 312 +++++---
 ...rverTransportProviderIntegrationTests.java | 242 ++++++
 .../spec/DefaultJsonSchemaValidatorTests.java | 698 ++++++++++++++++++
 .../spec/McpSchemaTests.java                  | 231 +++++-
 pom.xml                                       |   1 +
 14 files changed, 2291 insertions(+), 140 deletions(-)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java

diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 26452fe95..fdec82377 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -127,6 +127,13 @@
 			test
 		
 
+		
+			net.javacrumbs.json-unit
+			json-unit-assertj
+			${json-unit-assertj.version}
+			test
+		
+
 	
 
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index 4d123055d..9ef2855b1 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -3,6 +3,8 @@
  */
 package io.modelcontextprotocol;
 
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
 import static org.assertj.core.api.Assertions.assertWith;
@@ -60,6 +62,7 @@
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
+import net.javacrumbs.jsonunit.core.Option;
 import reactor.core.publisher.Mono;
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
@@ -1122,4 +1125,261 @@ void testPingSuccess(String clientType) {
 		mcpServer.closeGracefully().block();
 	}
 
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					String expression = (String) request.getOrDefault("expression", "2 + 3");
+					double result = evaluateExpression(expression);
+					return CallToolResult.builder()
+						.structuredContent(
+								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationFailure(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return invalid structured output. Result should be number, missing
+					// operation
+					return CallToolResult.builder()
+						.addTextContent("Invalid calculation")
+						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputMissingStructuredContent(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return result without structured content but tool has output schema
+					return CallToolResult.builder().addTextContent("Calculation completed").build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputRuntimeToolAddition(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Start server without tools
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
+					(exchange, request) -> {
+						int count = (Integer) request.getOrDefault("count", 1);
+						return CallToolResult.builder()
+							.addTextContent("Dynamic tool executed " + count + " times")
+							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+							.build();
+					});
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
 }
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 48d1c3465..4c6d37bf9 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -128,7 +128,14 @@
 			test
 		
 
+		
+			net.javacrumbs.json-unit
+			json-unit-assertj
+			${json-unit-assertj.version}
+			test
+		
+
 	
 
 
-
\ No newline at end of file
+
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index e854c37d4..9f2d6abff 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -48,6 +48,22 @@
 import reactor.core.scheduler.Schedulers;
 import reactor.test.StepVerifier;
 
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerResponse;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.awaitility.Awaitility.await;
+import static org.mockito.Mockito.mock;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+
+import net.javacrumbs.jsonunit.core.Option;
+
 class WebMvcSseIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
@@ -914,9 +930,6 @@ void testInitialize() {
 		mcpServer.close();
 	}
 
-	// ---------------------------------------
-	// Ping Tests
-	// ---------------------------------------
 	@Test
 	void testPingSuccess() {
 		// Create server with a tool that uses ping functionality
@@ -968,4 +981,254 @@ void testPingSuccess() {
 		mcpServer.close();
 	}
 
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+
+	@Test
+	void testStructuredOutputValidationSuccess() {
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					String expression = (String) request.getOrDefault("expression", "2 + 3");
+					double result = evaluateExpression(expression);
+					return CallToolResult.builder()
+						.structuredContent(
+								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			// In WebMVC, structured content is returned properly
+			if (response.structuredContent() != null) {
+				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+					.containsEntry("operation", "2 + 3")
+					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
+			}
+			else {
+				// Fallback to checking content if structured content is not available
+				assertThat(response.content()).isNotEmpty();
+			}
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testStructuredOutputValidationFailure() {
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return invalid structured output. Result should be number, missing
+					// operation
+					return CallToolResult.builder()
+						.addTextContent("Invalid calculation")
+						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testStructuredOutputMissingStructuredContent() {
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return result without structured content but tool has output schema
+					return CallToolResult.builder().addTextContent("Calculation completed").build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testStructuredOutputRuntimeToolAddition() {
+		// Start server without tools
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
+					(exchange, request) -> {
+						int count = (Integer) request.getOrDefault("count", 1);
+						return CallToolResult.builder()
+							.addTextContent("Dynamic tool executed " + count + " times")
+							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+							.build();
+					});
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
 }
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 829b99bc1..de4ee988a 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -83,6 +83,22 @@
 			reactor-core
 		
 
+		
+			com.networknt
+			json-schema-validator
+			${json-schema-validator.version}
+		
+
+		
+		
+			jakarta.servlet
+			jakarta.servlet-api
+			${jakarta.servlet.version}
+			provided
+		
+
+		
+
 		
 			org.springframework
 			spring-webmvc
@@ -179,15 +195,6 @@
 			test
 		
 
-
-		
-		
-			jakarta.servlet
-			jakarta.servlet-api
-			${jakarta.servlet.version}
-			provided
-		
-
 		
 		
 			org.apache.tomcat.embed
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index b06af9e85..d873a7fde 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -15,8 +15,13 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.BiFunction;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.spec.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -28,11 +33,10 @@
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.Utils;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
@@ -86,6 +90,8 @@ public class McpAsyncServer {
 
 	private final ObjectMapper objectMapper;
 
+	private final JsonSchemaValidator jsonSchemaValidator;
+
 	private final McpSchema.ServerCapabilities serverCapabilities;
 
 	private final McpSchema.Implementation serverInfo;
@@ -119,18 +125,19 @@ public class McpAsyncServer {
 	 */
 	McpAsyncServer(McpServerTransportProvider mcpTransportProvider, ObjectMapper objectMapper,
 			McpServerFeatures.Async features, Duration requestTimeout,
-			McpUriTemplateManagerFactory uriTemplateManagerFactory) {
+			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator) {
 		this.mcpTransportProvider = mcpTransportProvider;
 		this.objectMapper = objectMapper;
 		this.serverInfo = features.serverInfo();
 		this.serverCapabilities = features.serverCapabilities();
 		this.instructions = features.instructions();
-		this.tools.addAll(features.tools());
+		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
 		this.resources.putAll(features.resources());
 		this.resourceTemplates.addAll(features.resourceTemplates());
 		this.prompts.putAll(features.prompts());
 		this.completions.putAll(features.completions());
 		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+		this.jsonSchemaValidator = jsonSchemaValidator;
 
 		Map> requestHandlers = new HashMap<>();
 
@@ -286,15 +293,17 @@ public Mono addTool(McpServerFeatures.AsyncToolSpecification toolSpecifica
 			return Mono.error(new McpError("Server must be configured with tool capabilities"));
 		}
 
+		var wrappedToolSpecification = withStructuredOutputHandling(this.jsonSchemaValidator, toolSpecification);
+
 		return Mono.defer(() -> {
 			// Check for duplicate tool names
-			if (this.tools.stream().anyMatch(th -> th.tool().name().equals(toolSpecification.tool().name()))) {
-				return Mono
-					.error(new McpError("Tool with name '" + toolSpecification.tool().name() + "' already exists"));
+			if (this.tools.stream().anyMatch(th -> th.tool().name().equals(wrappedToolSpecification.tool().name()))) {
+				return Mono.error(
+						new McpError("Tool with name '" + wrappedToolSpecification.tool().name() + "' already exists"));
 			}
 
-			this.tools.add(toolSpecification);
-			logger.debug("Added tool handler: {}", toolSpecification.tool().name());
+			this.tools.add(wrappedToolSpecification);
+			logger.debug("Added tool handler: {}", wrappedToolSpecification.tool().name());
 
 			if (this.serverCapabilities.tools().listChanged()) {
 				return notifyToolsListChanged();
@@ -303,6 +312,107 @@ public Mono addTool(McpServerFeatures.AsyncToolSpecification toolSpecifica
 		});
 	}
 
+	private static class StructuredOutputCallToolHandler
+			implements BiFunction, Mono> {
+
+		private final BiFunction, Mono> delegateCallToolResult;
+
+		private final JsonSchemaValidator jsonSchemaValidator;
+
+		private final Map outputSchema;
+
+		public StructuredOutputCallToolHandler(JsonSchemaValidator jsonSchemaValidator,
+				Map outputSchema,
+				BiFunction, Mono> delegateHandler) {
+
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			Assert.notNull(delegateHandler, "Delegate call tool result handler must not be null");
+
+			this.delegateCallToolResult = delegateHandler;
+			this.outputSchema = outputSchema;
+			this.jsonSchemaValidator = jsonSchemaValidator;
+		}
+
+		@Override
+		public Mono apply(McpAsyncServerExchange exchange, Map arguments) {
+
+			return this.delegateCallToolResult.apply(exchange, arguments).map(result -> {
+
+				if (outputSchema == null) {
+					if (result.structuredContent() != null) {
+						logger.warn(
+								"Tool call with no outputSchema is not expected to have a result with structured content, but got: {}",
+								result.structuredContent());
+					}
+					// Pass through. No validation is required if no output schema is
+					// provided.
+					return result;
+				}
+
+				// If an output schema is provided, servers MUST provide structured
+				// results that conform to this schema.
+				// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema
+				if (result.structuredContent() == null) {
+					logger.warn(
+							"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+					return new CallToolResult(
+							"Response missing structured content which is expected when calling tool with non-empty outputSchema",
+							true);
+				}
+
+				// Validate the result against the output schema
+				var validation = this.jsonSchemaValidator.validate(outputSchema, result.structuredContent());
+
+				if (!validation.valid()) {
+					logger.warn("Tool call result validation failed: {}", validation.errorMessage());
+					return new CallToolResult(validation.errorMessage(), true);
+				}
+
+				if (Utils.isEmpty(result.content())) {
+					// For backwards compatibility, a tool that returns structured
+					// content SHOULD also return functionally equivalent unstructured
+					// content. (For example, serialized JSON can be returned in a
+					// TextContent block.)
+					// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
+
+					return new CallToolResult(List.of(new McpSchema.TextContent(validation.jsonStructuredOutput())),
+							result.isError(), result.structuredContent());
+				}
+
+				return result;
+			});
+		}
+
+	}
+
+	private static List withStructuredOutputHandling(
+			JsonSchemaValidator jsonSchemaValidator, List tools) {
+
+		if (Utils.isEmpty(tools)) {
+			return tools;
+		}
+
+		return tools.stream().map(tool -> withStructuredOutputHandling(jsonSchemaValidator, tool)).toList();
+	}
+
+	private static McpServerFeatures.AsyncToolSpecification withStructuredOutputHandling(
+			JsonSchemaValidator jsonSchemaValidator, McpServerFeatures.AsyncToolSpecification toolSpecification) {
+
+		if (toolSpecification.call() instanceof StructuredOutputCallToolHandler) {
+			// If the tool is already wrapped, return it as is
+			return toolSpecification;
+		}
+
+		if (toolSpecification.tool().outputSchema() == null) {
+			// If the tool does not have an output schema, return it as is
+			return toolSpecification;
+		}
+
+		return new McpServerFeatures.AsyncToolSpecification(toolSpecification.tool(),
+				new StructuredOutputCallToolHandler(jsonSchemaValidator, toolSpecification.tool().outputSchema(),
+						toolSpecification.call()));
+	}
+
 	/**
 	 * Remove a tool handler at runtime.
 	 * @param toolName The name of the tool handler to remove
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
index 63b589223..d4b8addf4 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -14,6 +14,9 @@
 import java.util.function.BiFunction;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.spec.DefaultJsonSchemaValidator;
+import io.modelcontextprotocol.spec.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
@@ -170,6 +173,8 @@ class AsyncSpecification {
 
 		private McpSchema.ServerCapabilities serverCapabilities;
 
+		private JsonSchemaValidator jsonSchemaValidator;
+
 		private String instructions;
 
 		/**
@@ -670,6 +675,20 @@ public AsyncSpecification objectMapper(ObjectMapper objectMapper) {
 			return this;
 		}
 
+		/**
+		 * Sets the JSON schema validator to use for validating tool and resource schemas.
+		 * This ensures that the server's tools and resources conform to the expected
+		 * schema definitions.
+		 * @param jsonSchemaValidator The validator to use. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if jsonSchemaValidator is null
+		 */
+		public AsyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			this.jsonSchemaValidator = jsonSchemaValidator;
+			return this;
+		}
+
 		/**
 		 * Builds an asynchronous MCP server that provides non-blocking operations.
 		 * @return A new instance of {@link McpAsyncServer} configured with this builder's
@@ -680,8 +699,10 @@ public McpAsyncServer build() {
 					this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers,
 					this.instructions);
 			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
+			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
+					: new DefaultJsonSchemaValidator(mapper);
 			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout,
-					this.uriTemplateManagerFactory);
+					this.uriTemplateManagerFactory, jsonSchemaValidator);
 		}
 
 	}
@@ -726,6 +747,8 @@ class SyncSpecification {
 
 		private final List resourceTemplates = new ArrayList<>();
 
+		private JsonSchemaValidator jsonSchemaValidator;
+
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
 		 * expose prompt templates to clients. Prompts allow servers to provide structured
@@ -1206,6 +1229,12 @@ public SyncSpecification objectMapper(ObjectMapper objectMapper) {
 			return this;
 		}
 
+		public SyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			this.jsonSchemaValidator = jsonSchemaValidator;
+			return this;
+		}
+
 		/**
 		 * Enable on "immediate execution" of the operations on the underlying
 		 * {@link McpAsyncServer}. Defaults to false, which does blocking code offloading
@@ -1234,8 +1263,11 @@ public McpSyncServer build() {
 			McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures,
 					this.immediateExecution);
 			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
+			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
+					: new DefaultJsonSchemaValidator(mapper);
+
 			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout,
-					this.uriTemplateManagerFactory);
+					this.uriTemplateManagerFactory, jsonSchemaValidator);
 
 			return new McpSyncServer(asyncServer, this.immediateExecution);
 		}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
new file mode 100644
index 000000000..cd8fc9659
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
@@ -0,0 +1,169 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+package io.modelcontextprotocol.spec;
+
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.networknt.schema.JsonSchema;
+import com.networknt.schema.JsonSchemaFactory;
+import com.networknt.schema.SpecVersion;
+import com.networknt.schema.ValidationMessage;
+
+import io.modelcontextprotocol.util.Assert;
+
+/**
+ * Default implementation of the {@link JsonSchemaValidator} interface. This class
+ * provides methods to validate structured content against a JSON schema. It uses the
+ * NetworkNT JSON Schema Validator library for validation.
+ *
+ * @author Christian Tzolov
+ */
+public class DefaultJsonSchemaValidator implements JsonSchemaValidator {
+
+	private static final Logger logger = LoggerFactory.getLogger(DefaultJsonSchemaValidator.class);
+
+	private final ObjectMapper objectMapper;
+
+	private final JsonSchemaFactory schemaFactory;
+
+	// TODO: Implement a strategy to purge the cache (TTL, size limit, etc.)
+	private final ConcurrentHashMap schemaCache;
+
+	public DefaultJsonSchemaValidator() {
+		this(new ObjectMapper());
+	}
+
+	public DefaultJsonSchemaValidator(ObjectMapper objectMapper) {
+		this.objectMapper = objectMapper;
+		this.schemaFactory = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012);
+		this.schemaCache = new ConcurrentHashMap<>();
+	}
+
+	@Override
+	public ValidationResponse validate(Map schema, Map structuredContent) {
+
+		Assert.notNull(schema, "Schema must not be null");
+		Assert.notNull(structuredContent, "Structured content must not be null");
+
+		try {
+
+			JsonNode jsonStructuredOutput = this.objectMapper.valueToTree(structuredContent);
+
+			Set validationResult = this.getOrCreateJsonSchema(schema).validate(jsonStructuredOutput);
+
+			// Check if validation passed
+			if (!validationResult.isEmpty()) {
+				return ValidationResponse
+					.asInvalid("Validation failed: structuredContent does not match tool outputSchema. "
+							+ "Validation errors: " + validationResult);
+			}
+
+			return ValidationResponse.asValid(jsonStructuredOutput.toString());
+
+		}
+		catch (JsonProcessingException e) {
+			logger.error("Failed to validate CallToolResult: Error parsing schema: {}", e);
+			return ValidationResponse.asInvalid("Error parsing tool JSON Schema: " + e.getMessage());
+		}
+		catch (Exception e) {
+			logger.error("Failed to validate CallToolResult: Unexpected error: {}", e);
+			return ValidationResponse.asInvalid("Unexpected validation error: " + e.getMessage());
+		}
+	}
+
+	/**
+	 * Gets a cached JsonSchema or creates and caches a new one.
+	 * @param schema the schema map to convert
+	 * @return the compiled JsonSchema
+	 * @throws JsonProcessingException if schema processing fails
+	 */
+	private JsonSchema getOrCreateJsonSchema(Map schema) throws JsonProcessingException {
+		// Generate cache key based on schema content
+		String cacheKey = this.generateCacheKey(schema);
+
+		// Try to get from cache first
+		JsonSchema cachedSchema = this.schemaCache.get(cacheKey);
+		if (cachedSchema != null) {
+			return cachedSchema;
+		}
+
+		// Create new schema if not in cache
+		JsonSchema newSchema = this.createJsonSchema(schema);
+
+		// Cache the schema
+		JsonSchema existingSchema = this.schemaCache.putIfAbsent(cacheKey, newSchema);
+		return existingSchema != null ? existingSchema : newSchema;
+	}
+
+	/**
+	 * Creates a new JsonSchema from the given schema map.
+	 * @param schema the schema map
+	 * @return the compiled JsonSchema
+	 * @throws JsonProcessingException if schema processing fails
+	 */
+	private JsonSchema createJsonSchema(Map schema) throws JsonProcessingException {
+		// Convert schema map directly to JsonNode (more efficient than string
+		// serialization)
+		JsonNode schemaNode = this.objectMapper.valueToTree(schema);
+
+		// Handle case where ObjectMapper might return null (e.g., in mocked scenarios)
+		if (schemaNode == null) {
+			throw new JsonProcessingException("Failed to convert schema to JsonNode") {
+			};
+		}
+
+		// Handle additionalProperties setting
+		if (schemaNode.isObject()) {
+			ObjectNode objectSchemaNode = (ObjectNode) schemaNode;
+			if (!objectSchemaNode.has("additionalProperties")) {
+				// Clone the node before modification to avoid mutating the original
+				objectSchemaNode = objectSchemaNode.deepCopy();
+				objectSchemaNode.put("additionalProperties", false);
+				schemaNode = objectSchemaNode;
+			}
+		}
+
+		return this.schemaFactory.getSchema(schemaNode);
+	}
+
+	/**
+	 * Generates a cache key for the given schema map.
+	 * @param schema the schema map
+	 * @return a cache key string
+	 */
+	protected String generateCacheKey(Map schema) {
+		if (schema.containsKey("$id")) {
+			// Use the (optional) "$id" field as the cache key if present
+			return "" + schema.get("$id");
+		}
+		// Fall back to schema's hash code as a simple cache key
+		// For more sophisticated caching, could use content-based hashing
+		return String.valueOf(schema.hashCode());
+	}
+
+	/**
+	 * Clears the schema cache. Useful for testing or memory management.
+	 */
+	public void clearCache() {
+		this.schemaCache.clear();
+	}
+
+	/**
+	 * Returns the current size of the schema cache.
+	 * @return the number of cached schemas
+	 */
+	public int getCacheSize() {
+		return this.schemaCache.size();
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java b/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
new file mode 100644
index 000000000..c95e627a9
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+package io.modelcontextprotocol.spec;
+
+import java.util.Map;
+
+/**
+ * Interface for validating structured content against a JSON schema. This interface
+ * defines a method to validate structured content based on the provided output schema.
+ *
+ * @author Christian Tzolov
+ */
+public interface JsonSchemaValidator {
+
+	/**
+	 * Represents the result of a validation operation.
+	 *
+	 * @param valid Indicates whether the validation was successful.
+	 * @param errorMessage An error message if the validation failed, otherwise null.
+	 * @param jsonStructuredOutput The text structured content in JSON format if the
+	 * validation was successful, otherwise null.
+	 */
+	public record ValidationResponse(boolean valid, String errorMessage, String jsonStructuredOutput) {
+
+		public static ValidationResponse asValid(String jsonStructuredOutput) {
+			return new ValidationResponse(true, null, jsonStructuredOutput);
+		}
+
+		public static ValidationResponse asInvalid(String message) {
+			return new ValidationResponse(false, message, null);
+		}
+	}
+
+	/**
+	 * Validates the structured content against the provided JSON schema.
+	 * @param schema The JSON schema to validate against.
+	 * @param structuredContent The structured content to validate.
+	 * @return A ValidationResponse indicating whether the validation was successful or
+	 * not.
+	 */
+	ValidationResponse validate(Map schema, Map structuredContent);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index acdc18e10..8362ca224 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -20,6 +20,9 @@
 import com.fasterxml.jackson.annotation.JsonTypeInfo.As;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -934,16 +937,26 @@ public record JsonSchema( // @formatter:off
 				@JsonProperty("definitions") Map definitions) {
 		} // @formatter:on
 
+	/**
+	 * Additional properties describing a Tool to clients.
+	 *
+	 * NOTE: all properties in ToolAnnotations are **hints**. They are not guaranteed to
+	 * provide a faithful description of tool behavior (including descriptive properties
+	 * like `title`).
+	 *
+	 * Clients should never make tool use decisions based on ToolAnnotations received from
+	 * untrusted servers.
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ToolAnnotations( // @formatter:off
-				@JsonProperty("title")  String title,
-				@JsonProperty("readOnlyHint")   Boolean readOnlyHint,
-				@JsonProperty("destructiveHint") Boolean destructiveHint,
-				@JsonProperty("idempotentHint") Boolean idempotentHint,
-				@JsonProperty("openWorldHint") Boolean openWorldHint,
-				@JsonProperty("returnDirect") Boolean returnDirect) {
-		} // @formatter:on
+		@JsonProperty("title")  String title,
+		@JsonProperty("readOnlyHint")   Boolean readOnlyHint,
+		@JsonProperty("destructiveHint") Boolean destructiveHint,
+		@JsonProperty("idempotentHint") Boolean idempotentHint,
+		@JsonProperty("openWorldHint") Boolean openWorldHint,
+		@JsonProperty("returnDirect") Boolean returnDirect) {
+	} // @formatter:on
 
 	/**
 	 * Represents a tool that the server provides. Tools enable servers to expose
@@ -957,17 +970,19 @@ public record ToolAnnotations( // @formatter:off
 	 * used by clients to improve the LLM's understanding of available tools.
 	 * @param inputSchema A JSON Schema object that describes the expected structure of
 	 * the arguments when calling this tool. This allows clients to validate tool
-	 * @param annotations Additional properties describing a Tool to clients. arguments
-	 * before sending them to the server.
+	 * @param outputSchema An optional JSON Schema object defining the structure of the
+	 * tool's output returned in the structuredContent field of a CallToolResult.
+	 * @param annotations Optional additional tool information.
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record Tool( // @formatter:off
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title,
-				@JsonProperty("description") String description,
-				@JsonProperty("inputSchema") JsonSchema inputSchema,
-				@JsonProperty("annotations") ToolAnnotations annotations) implements BaseMetadata { // @formatter:on
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title,
+		@JsonProperty("description") String description,
+		@JsonProperty("inputSchema") JsonSchema inputSchema,
+		@JsonProperty("outputSchema") Map outputSchema,
+		@JsonProperty("annotations") ToolAnnotations annotations) {// @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -975,15 +990,35 @@ public record Tool( // @formatter:off
 		 */
 		@Deprecated
 		public Tool(String name, String description, JsonSchema inputSchema, ToolAnnotations annotations) {
-			this(name, null, description, inputSchema, annotations);
+			this(name, null, description, inputSchema, null, annotations);
 		}
 
-		public Tool(String name, String description, String schema) {
-			this(name, null, description, parseSchema(schema), null);
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link Tool#builder()} instead.
+		 */
+		@Deprecated
+		public Tool(String name, String description, String inputSchema) {
+			this(name, null, description, parseSchema(inputSchema), null, null);
 		}
 
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link Tool#builder()} instead.
+		 */
+		@Deprecated
 		public Tool(String name, String description, String schema, ToolAnnotations annotations) {
-			this(name, null, description, parseSchema(schema), annotations);
+			this(name, null, description, parseSchema(schema), null, annotations);
+		}
+
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link Tool#builder()} instead.
+		 */
+		@Deprecated
+		public Tool(String name, String description, String inputSchema, String outputSchema,
+				ToolAnnotations annotations) {
+			this(name, null, description, parseSchema(inputSchema), schemaToMap(outputSchema), annotations);
 		}
 
 		public static Builder builder() {
@@ -1000,6 +1035,8 @@ public static class Builder {
 
 			private JsonSchema inputSchema;
 
+			private Map outputSchema;
+
 			private ToolAnnotations annotations;
 
 			public Builder name(String name) {
@@ -1022,6 +1059,21 @@ public Builder inputSchema(JsonSchema inputSchema) {
 				return this;
 			}
 
+			public Builder inputSchema(String inputSchema) {
+				this.inputSchema = parseSchema(inputSchema);
+				return this;
+			}
+
+			public Builder outputSchema(Map outputSchema) {
+				this.outputSchema = outputSchema;
+				return this;
+			}
+
+			public Builder outputSchema(String outputSchema) {
+				this.outputSchema = schemaToMap(outputSchema);
+				return this;
+			}
+
 			public Builder annotations(ToolAnnotations annotations) {
 				this.annotations = annotations;
 				return this;
@@ -1029,12 +1081,19 @@ public Builder annotations(ToolAnnotations annotations) {
 
 			public Tool build() {
 				Assert.hasText(name, "name must not be empty");
-
-				return new Tool(name, title, description, inputSchema, annotations);
+				return new Tool(name, title, description, inputSchema, outputSchema, annotations);
 			}
 
 		}
+	}
 
+	private static Map schemaToMap(String schema) {
+		try {
+			return OBJECT_MAPPER.readValue(schema, MAP_TYPE_REF);
+		}
+		catch (IOException e) {
+			throw new IllegalArgumentException("Invalid schema: " + schema, e);
+		}
 	}
 
 	private static JsonSchema parseSchema(String schema) {
@@ -1059,7 +1118,7 @@ private static JsonSchema parseSchema(String schema) {
 	public record CallToolRequest(// @formatter:off
 				@JsonProperty("name") String name,
 				@JsonProperty("arguments") Map arguments,
-				@JsonProperty("_meta") Map meta) implements Request {
+				@JsonProperty("_meta") Map meta) implements Request {// @formatter:off
 
 				public CallToolRequest(String name, String jsonArguments) {
 						this(name, parseJsonArguments(jsonArguments), null);
@@ -1119,7 +1178,7 @@ public CallToolRequest build() {
 								return new CallToolRequest(name, arguments, meta);
 						}
 				}
-		}// @formatter:off
+		}
 
 		/**
 		 * The server's response to a tools/call request from the client.
@@ -1128,110 +1187,137 @@ public CallToolRequest build() {
 		 *                or an embedded resource.
 		 * @param isError If true, indicates that the tool execution failed and the content contains error information.
 		 *                If false or absent, indicates successful execution.
+		 * @param structuredContent An optional JSON object that represents the structured result of the tool call.
 		 */
 		@JsonInclude(JsonInclude.Include.NON_ABSENT)
 		@JsonIgnoreProperties(ignoreUnknown = true)
 		public record CallToolResult( // @formatter:off
 				@JsonProperty("content") List content,
-				@JsonProperty("isError") Boolean isError) {
+				@JsonProperty("isError") Boolean isError,
+				@JsonProperty("structuredContent") Map structuredContent) {// @formatter:on
 
-				/**
-				 * Creates a new instance of {@link CallToolResult} with a string containing the
-				 * tool result.
-				 *
-				 * @param content The content of the tool result. This will be mapped to a one-sized list
-				 * 				  with a {@link TextContent} element.
-				 * @param isError If true, indicates that the tool execution failed and the content contains error information.
-				 *                If false or absent, indicates successful execution.
-				 */
-				public CallToolResult(String content, Boolean isError) {
-						this(List.of(new TextContent(content)), isError);
-				}
+		// backwards compatibility constructor
+		public CallToolResult(List content, Boolean isError) {
+			this(content, isError, null);
+		}
 
-				/**
-				 * Creates a builder for {@link CallToolResult}.
-				 * @return a new builder instance
-				 */
-				public static Builder builder() {
-						return new Builder();
-				}
+		/**
+		 * Creates a new instance of {@link CallToolResult} with a string containing the
+		 * tool result.
+		 * @param content The content of the tool result. This will be mapped to a
+		 * one-sized list with a {@link TextContent} element.
+		 * @param isError If true, indicates that the tool execution failed and the
+		 * content contains error information. If false or absent, indicates successful
+		 * execution.
+		 */
+		public CallToolResult(String content, Boolean isError) {
+			this(List.of(new TextContent(content)), isError);
+		}
 
-				/**
-				 * Builder for {@link CallToolResult}.
-				 */
-				public static class Builder {
-						private List content = new ArrayList<>();
-						private Boolean isError;
-
-						/**
-						 * Sets the content list for the tool result.
-						 * @param content the content list
-						 * @return this builder
-						 */
-						public Builder content(List content) {
-								Assert.notNull(content, "content must not be null");
-								this.content = content;
-								return this;
-						}
+		/**
+		 * Creates a builder for {@link CallToolResult}.
+		 * @return a new builder instance
+		 */
+		public static Builder builder() {
+			return new Builder();
+		}
 
-						/**
-						 * Sets the text content for the tool result.
-						 * @param textContent the text content
-						 * @return this builder
-						 */
-						public Builder textContent(List textContent) {
-								Assert.notNull(textContent, "textContent must not be null");
-								textContent.stream()
-										.map(TextContent::new)
-										.forEach(this.content::add);
-								return this;
-						}
+		/**
+		 * Builder for {@link CallToolResult}.
+		 */
+		public static class Builder {
 
-						/**
-						 * Adds a content item to the tool result.
-						 * @param contentItem the content item to add
-						 * @return this builder
-						 */
-						public Builder addContent(Content contentItem) {
-								Assert.notNull(contentItem, "contentItem must not be null");
-								if (this.content == null) {
-										this.content = new ArrayList<>();
-								}
-								this.content.add(contentItem);
-								return this;
-						}
+			private List content = new ArrayList<>();
 
-						/**
-						 * Adds a text content item to the tool result.
-						 * @param text the text content
-						 * @return this builder
-						 */
-						public Builder addTextContent(String text) {
-								Assert.notNull(text, "text must not be null");
-								return addContent(new TextContent(text));
-						}
+			private Boolean isError = false;
 
-						/**
-						 * Sets whether the tool execution resulted in an error.
-						 * @param isError true if the tool execution failed, false otherwise
-						 * @return this builder
-						 */
-						public Builder isError(Boolean isError) {
-								Assert.notNull(isError, "isError must not be null");
-								this.isError = isError;
-								return this;
-						}
+			private Map structuredContent;
 
-						/**
-						 * Builds a new {@link CallToolResult} instance.
-						 * @return a new CallToolResult instance
-						 */
-						public CallToolResult build() {
-								return new CallToolResult(content, isError);
-						}
+			/**
+			 * Sets the content list for the tool result.
+			 * @param content the content list
+			 * @return this builder
+			 */
+			public Builder content(List content) {
+				Assert.notNull(content, "content must not be null");
+				this.content = content;
+				return this;
+			}
+
+			public Builder structuredContent(Map structuredContent) {
+				Assert.notNull(structuredContent, "structuredContent must not be null");
+				this.structuredContent = structuredContent;
+				return this;
+			}
+
+			public Builder structuredContent(String structuredContent) {
+				Assert.hasText(structuredContent, "structuredContent must not be empty");
+				try {
+					this.structuredContent = OBJECT_MAPPER.readValue(structuredContent, MAP_TYPE_REF);
+				}
+				catch (IOException e) {
+					throw new IllegalArgumentException("Invalid structured content: " + structuredContent, e);
 				}
+				return this;
+			}
 
-		} // @formatter:on
+			/**
+			 * Sets the text content for the tool result.
+			 * @param textContent the text content
+			 * @return this builder
+			 */
+			public Builder textContent(List textContent) {
+				Assert.notNull(textContent, "textContent must not be null");
+				textContent.stream().map(TextContent::new).forEach(this.content::add);
+				return this;
+			}
+
+			/**
+			 * Adds a content item to the tool result.
+			 * @param contentItem the content item to add
+			 * @return this builder
+			 */
+			public Builder addContent(Content contentItem) {
+				Assert.notNull(contentItem, "contentItem must not be null");
+				if (this.content == null) {
+					this.content = new ArrayList<>();
+				}
+				this.content.add(contentItem);
+				return this;
+			}
+
+			/**
+			 * Adds a text content item to the tool result.
+			 * @param text the text content
+			 * @return this builder
+			 */
+			public Builder addTextContent(String text) {
+				Assert.notNull(text, "text must not be null");
+				return addContent(new TextContent(text));
+			}
+
+			/**
+			 * Sets whether the tool execution resulted in an error.
+			 * @param isError true if the tool execution failed, false otherwise
+			 * @return this builder
+			 */
+			public Builder isError(Boolean isError) {
+				Assert.notNull(isError, "isError must not be null");
+				this.isError = isError;
+				return this;
+			}
+
+			/**
+			 * Builds a new {@link CallToolResult} instance.
+			 * @return a new CallToolResult instance
+			 */
+			public CallToolResult build() {
+				return new CallToolResult(content, isError, structuredContent);
+			}
+
+		}
+
+	}
 
 	// ---------------------------
 	// Sampling Interfaces
@@ -1286,7 +1372,7 @@ public ModelPreferences build() {
 						return new ModelPreferences(hints, costPriority, speedPriority, intelligencePriority);
 				}
 		}
-} // @formatter:on
+	} // @formatter:on
 
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -1482,7 +1568,7 @@ public CreateMessageResult build() {
 	/**
 	 * Used by the server to send an elicitation to the client.
 	 *
-	 * @param message The body of the elicitation message.
+	 * @param errorMessage The body of the elicitation message.
 	 * @param requestedSchema The elicitation response schema that must be satisfied.
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
index ac10df4f5..66f33fb67 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
@@ -32,6 +32,8 @@
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
+import net.javacrumbs.jsonunit.core.Option;
+
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
 import org.apache.catalina.startup.Tomcat;
@@ -48,6 +50,8 @@
 import static org.assertj.core.api.InstanceOfAssertFactories.type;
 import static org.awaitility.Awaitility.await;
 import static org.mockito.Mockito.mock;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 
 class HttpServletSseServerTransportProviderIntegrationTests {
 
@@ -1070,4 +1074,242 @@ void testPingSuccess() {
 		mcpServer.close();
 	}
 
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+	@Test
+	void testStructuredOutputValidationSuccess() {
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					String expression = (String) request.getOrDefault("expression", "2 + 3");
+					double result = evaluateExpression(expression);
+					return CallToolResult.builder()
+						.structuredContent(
+								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+
+			// Verify structured content (may be null in sync server but validation still
+			// works)
+			if (response.structuredContent() != null) {
+				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+					.containsEntry("operation", "2 + 3")
+					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
+			}
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testStructuredOutputValidationFailure() {
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return invalid structured output. Result should be number, missing
+					// operation
+					return CallToolResult.builder()
+						.addTextContent("Invalid calculation")
+						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testStructuredOutputMissingStructuredContent() {
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return result without structured content but tool has output schema
+					return CallToolResult.builder().addTextContent("Calculation completed").build();
+				});
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@Test
+	void testStructuredOutputRuntimeToolAddition() {
+		// Start server without tools
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
+					(exchange, request) -> {
+						int count = (Integer) request.getOrDefault("count", 1);
+						return CallToolResult.builder()
+							.addTextContent("Dynamic tool executed " + count + " times")
+							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+							.build();
+					});
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.structuredContent()).containsEntry("message", "Dynamic execution")
+				.containsEntry("count", 3);
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
new file mode 100644
index 000000000..9da31b38b
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
@@ -0,0 +1,698 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+package io.modelcontextprotocol.spec;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+
+import java.util.Map;
+import java.util.stream.Stream;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.spec.DefaultJsonSchemaValidator;
+import io.modelcontextprotocol.spec.JsonSchemaValidator.ValidationResponse;
+
+/**
+ * Tests for {@link DefaultJsonSchemaValidator}.
+ *
+ * @author Christian Tzolov
+ */
+class DefaultJsonSchemaValidatorTests {
+
+	private DefaultJsonSchemaValidator validator;
+
+	private ObjectMapper objectMapper;
+
+	@Mock
+	private ObjectMapper mockObjectMapper;
+
+	@BeforeEach
+	void setUp() {
+		MockitoAnnotations.openMocks(this);
+		validator = new DefaultJsonSchemaValidator();
+		objectMapper = new ObjectMapper();
+	}
+
+	/**
+	 * Utility method to convert JSON string to Map
+	 */
+	private Map toMap(String json) {
+		try {
+			return objectMapper.readValue(json, new TypeReference>() {
+			});
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to parse JSON: " + json, e);
+		}
+	}
+
+	@Test
+	void testDefaultConstructor() {
+		DefaultJsonSchemaValidator defaultValidator = new DefaultJsonSchemaValidator();
+
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"test": {"type": "string"}
+					}
+				}
+				""";
+		String contentJson = """
+				{
+					"test": "value"
+				}
+				""";
+
+		ValidationResponse response = defaultValidator.validate(toMap(schemaJson), toMap(contentJson));
+		assertTrue(response.valid());
+	}
+
+	@Test
+	void testConstructorWithObjectMapper() {
+		ObjectMapper customMapper = new ObjectMapper();
+		DefaultJsonSchemaValidator customValidator = new DefaultJsonSchemaValidator(customMapper);
+
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"test": {"type": "string"}
+					}
+				}
+				""";
+		String contentJson = """
+				{
+					"test": "value"
+				}
+				""";
+
+		ValidationResponse response = customValidator.validate(toMap(schemaJson), toMap(contentJson));
+		assertTrue(response.valid());
+	}
+
+	@Test
+	void testValidateWithValidStringSchema() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"},
+						"age": {"type": "integer"}
+					},
+					"required": ["name", "age"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"name": "John Doe",
+					"age": 30
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+		assertNotNull(response.jsonStructuredOutput());
+	}
+
+	@Test
+	void testValidateWithValidNumberSchema() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"price": {"type": "number", "minimum": 0},
+						"quantity": {"type": "integer", "minimum": 1}
+					},
+					"required": ["price", "quantity"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"price": 19.99,
+					"quantity": 5
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
+	@Test
+	void testValidateWithValidArraySchema() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"items": {
+							"type": "array",
+							"items": {"type": "string"}
+						}
+					},
+					"required": ["items"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"items": ["apple", "banana", "cherry"]
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
+	@Test
+	void testValidateWithInvalidTypeSchema() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"},
+						"age": {"type": "integer"}
+					},
+					"required": ["name", "age"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"name": "John Doe",
+					"age": "thirty"
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertFalse(response.valid());
+		assertNotNull(response.errorMessage());
+		assertTrue(response.errorMessage().contains("Validation failed"));
+		assertTrue(response.errorMessage().contains("structuredContent does not match tool outputSchema"));
+	}
+
+	@Test
+	void testValidateWithMissingRequiredField() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"},
+						"age": {"type": "integer"}
+					},
+					"required": ["name", "age"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"name": "John Doe"
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertFalse(response.valid());
+		assertNotNull(response.errorMessage());
+		assertTrue(response.errorMessage().contains("Validation failed"));
+	}
+
+	@Test
+	void testValidateWithAdditionalPropertiesNotAllowed() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"}
+					},
+					"required": ["name"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"name": "John Doe",
+					"extraField": "should not be allowed"
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertFalse(response.valid());
+		assertNotNull(response.errorMessage());
+		assertTrue(response.errorMessage().contains("Validation failed"));
+	}
+
+	@Test
+	void testValidateWithAdditionalPropertiesExplicitlyAllowed() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"}
+					},
+					"required": ["name"],
+					"additionalProperties": true
+				}
+				""";
+
+		String contentJson = """
+				{
+					"name": "John Doe",
+					"extraField": "should be allowed"
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
+	@Test
+	void testValidateWithAdditionalPropertiesExplicitlyDisallowed() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"}
+					},
+					"required": ["name"],
+					"additionalProperties": false
+				}
+				""";
+
+		String contentJson = """
+				{
+					"name": "John Doe",
+					"extraField": "should not be allowed"
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertFalse(response.valid());
+		assertNotNull(response.errorMessage());
+		assertTrue(response.errorMessage().contains("Validation failed"));
+	}
+
+	@Test
+	void testValidateWithEmptySchema() {
+		String schemaJson = """
+				{
+					"additionalProperties": true
+				}
+				""";
+
+		String contentJson = """
+				{
+					"anything": "goes"
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
+	@Test
+	void testValidateWithEmptyContent() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {}
+				}
+				""";
+
+		String contentJson = """
+				{}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
+	@Test
+	void testValidateWithNestedObjectSchema() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"person": {
+							"type": "object",
+							"properties": {
+								"name": {"type": "string"},
+								"address": {
+									"type": "object",
+									"properties": {
+										"street": {"type": "string"},
+										"city": {"type": "string"}
+									},
+									"required": ["street", "city"]
+								}
+							},
+							"required": ["name", "address"]
+						}
+					},
+					"required": ["person"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"person": {
+						"name": "John Doe",
+						"address": {
+							"street": "123 Main St",
+							"city": "Anytown"
+						}
+					}
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
+	@Test
+	void testValidateWithInvalidNestedObjectSchema() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"person": {
+							"type": "object",
+							"properties": {
+								"name": {"type": "string"},
+								"address": {
+									"type": "object",
+									"properties": {
+										"street": {"type": "string"},
+										"city": {"type": "string"}
+									},
+									"required": ["street", "city"]
+								}
+							},
+							"required": ["name", "address"]
+						}
+					},
+					"required": ["person"]
+				}
+				""";
+
+		String contentJson = """
+				{
+					"person": {
+						"name": "John Doe",
+						"address": {
+							"street": "123 Main St"
+						}
+					}
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertFalse(response.valid());
+		assertNotNull(response.errorMessage());
+		assertTrue(response.errorMessage().contains("Validation failed"));
+	}
+
+	@Test
+	void testValidateWithJsonProcessingException() throws Exception {
+		DefaultJsonSchemaValidator validatorWithMockMapper = new DefaultJsonSchemaValidator(mockObjectMapper);
+
+		Map schema = Map.of("type", "object");
+		Map structuredContent = Map.of("key", "value");
+
+		// This will trigger our null check and throw JsonProcessingException
+		when(mockObjectMapper.valueToTree(any())).thenReturn(null);
+
+		ValidationResponse response = validatorWithMockMapper.validate(schema, structuredContent);
+
+		assertFalse(response.valid());
+		assertNotNull(response.errorMessage());
+		assertTrue(response.errorMessage().contains("Error parsing tool JSON Schema"));
+		assertTrue(response.errorMessage().contains("Failed to convert schema to JsonNode"));
+	}
+
+	@ParameterizedTest
+	@MethodSource("provideValidSchemaAndContentPairs")
+	void testValidateWithVariousValidInputs(Map schema, Map content) {
+		ValidationResponse response = validator.validate(schema, content);
+
+		assertTrue(response.valid(), "Expected validation to pass for schema: " + schema + " and content: " + content);
+		assertNull(response.errorMessage());
+	}
+
+	@ParameterizedTest
+	@MethodSource("provideInvalidSchemaAndContentPairs")
+	void testValidateWithVariousInvalidInputs(Map schema, Map content) {
+		ValidationResponse response = validator.validate(schema, content);
+
+		assertFalse(response.valid(), "Expected validation to fail for schema: " + schema + " and content: " + content);
+		assertNotNull(response.errorMessage());
+		assertTrue(response.errorMessage().contains("Validation failed"));
+	}
+
+	private static Map staticToMap(String json) {
+		try {
+			ObjectMapper mapper = new ObjectMapper();
+			return mapper.readValue(json, new TypeReference>() {
+			});
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to parse JSON: " + json, e);
+		}
+	}
+
+	private static Stream provideValidSchemaAndContentPairs() {
+		return Stream.of(
+				// Boolean schema
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"flag": {"type": "boolean"}
+							}
+						}
+						"""), staticToMap("""
+						{
+							"flag": true
+						}
+						""")),
+				// String with additional properties allowed
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"name": {"type": "string"}
+							},
+							"additionalProperties": true
+						}
+						"""), staticToMap("""
+						{
+							"name": "test",
+							"extra": "allowed"
+						}
+						""")),
+				// Array with specific items
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"numbers": {
+									"type": "array",
+									"items": {"type": "number"}
+								}
+							}
+						}
+						"""), staticToMap("""
+						{
+							"numbers": [1.0, 2.5, 3.14]
+						}
+						""")),
+				// Enum validation
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"status": {
+									"type": "string",
+									"enum": ["active", "inactive", "pending"]
+								}
+							}
+						}
+						"""), staticToMap("""
+						{
+							"status": "active"
+						}
+						""")));
+	}
+
+	private static Stream provideInvalidSchemaAndContentPairs() {
+		return Stream.of(
+				// Wrong boolean type
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"flag": {"type": "boolean"}
+							}
+						}
+						"""), staticToMap("""
+						{
+							"flag": "true"
+						}
+						""")),
+				// Array with wrong item types
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"numbers": {
+									"type": "array",
+									"items": {"type": "number"}
+								}
+							}
+						}
+						"""), staticToMap("""
+						{
+							"numbers": ["one", "two", "three"]
+						}
+						""")),
+				// Invalid enum value
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"status": {
+									"type": "string",
+									"enum": ["active", "inactive", "pending"]
+								}
+							}
+						}
+						"""), staticToMap("""
+						{
+							"status": "unknown"
+						}
+						""")),
+				// Minimum constraint violation
+				Arguments.of(staticToMap("""
+						{
+							"type": "object",
+							"properties": {
+								"age": {"type": "integer", "minimum": 0}
+							}
+						}
+						"""), staticToMap("""
+						{
+							"age": -5
+						}
+						""")));
+	}
+
+	@Test
+	void testValidationResponseToValid() {
+		String jsonOutput = "{\"test\":\"value\"}";
+		ValidationResponse response = ValidationResponse.asValid(jsonOutput);
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+		assertEquals(jsonOutput, response.jsonStructuredOutput());
+	}
+
+	@Test
+	void testValidationResponseToInvalid() {
+		String errorMessage = "Test error message";
+		ValidationResponse response = ValidationResponse.asInvalid(errorMessage);
+		assertFalse(response.valid());
+		assertEquals(errorMessage, response.errorMessage());
+		assertNull(response.jsonStructuredOutput());
+	}
+
+	@Test
+	void testValidationResponseRecord() {
+		ValidationResponse response1 = new ValidationResponse(true, null, "{\"valid\":true}");
+		ValidationResponse response2 = new ValidationResponse(false, "Error", null);
+
+		assertTrue(response1.valid());
+		assertNull(response1.errorMessage());
+		assertEquals("{\"valid\":true}", response1.jsonStructuredOutput());
+
+		assertFalse(response2.valid());
+		assertEquals("Error", response2.errorMessage());
+		assertNull(response2.jsonStructuredOutput());
+
+		// Test equality
+		ValidationResponse response3 = new ValidationResponse(true, null, "{\"valid\":true}");
+		assertEquals(response1, response3);
+		assertNotEquals(response1, response2);
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index 1d0ba302b..df7ab514f 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -830,9 +830,234 @@ void testToolWithAnnotations() throws Exception {
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
-			.isEqualTo(
-					json("""
-							{"name":"test-tool","description":"A test tool","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"number"}},"required":["name"]},"annotations":{"title":"A test tool","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false,"returnDirect":false}}"""));
+			.isEqualTo(json("""
+					{
+						"name":"test-tool",
+						"description":"A test tool",
+						"inputSchema":{
+							"type":"object",
+							"properties":{
+								"name":{"type":"string"},
+								"value":{"type":"number"}
+							},
+							"required":["name"]
+						},
+						"annotations":{
+							"title":"A test tool",
+							"readOnlyHint":false,
+							"destructiveHint":false,
+							"idempotentHint":false,
+							"openWorldHint":false,
+							"returnDirect":false
+						}
+					}
+					"""));
+	}
+
+	@Test
+	void testToolWithOutputSchema() throws Exception {
+		String inputSchemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {
+							"type": "string"
+						},
+						"value": {
+							"type": "number"
+						}
+					},
+					"required": ["name"]
+				}
+				""";
+
+		String outputSchemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"result": {
+							"type": "string"
+						},
+						"status": {
+							"type": "string",
+							"enum": ["success", "error"]
+						}
+					},
+					"required": ["result", "status"]
+				}
+				""";
+
+		McpSchema.Tool tool = new McpSchema.Tool("test-tool", "A test tool", inputSchemaJson, outputSchemaJson, null);
+
+		String value = mapper.writeValueAsString(tool);
+		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
+			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+			.isObject()
+			.isEqualTo(json("""
+					{
+						"name":"test-tool",
+						"description":"A test tool",
+						"inputSchema":{
+							"type":"object",
+							"properties":{
+								"name":{"type":"string"},
+								"value":{"type":"number"}
+							},
+							"required":["name"]
+						},
+						"outputSchema":{
+							"type":"object",
+							"properties":{
+								"result":{"type":"string"},
+								"status":{
+									"type":"string",
+									"enum":["success","error"]
+								}
+							},
+							"required":["result","status"]
+						}
+					}
+					"""));
+	}
+
+	@Test
+	void testToolWithOutputSchemaAndAnnotations() throws Exception {
+		String inputSchemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {
+							"type": "string"
+						}
+					},
+					"required": ["name"]
+				}
+				""";
+
+		String outputSchemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"result": {
+							"type": "string"
+						}
+					},
+					"required": ["result"]
+				}
+				""";
+
+		McpSchema.ToolAnnotations annotations = new McpSchema.ToolAnnotations("A test tool with output", true, false,
+				true, false, true);
+
+		McpSchema.Tool tool = new McpSchema.Tool("test-tool", "A test tool", inputSchemaJson, outputSchemaJson,
+				annotations);
+
+		String value = mapper.writeValueAsString(tool);
+		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
+			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+			.isObject()
+			.isEqualTo(json("""
+					{
+						"name":"test-tool",
+						"description":"A test tool",
+						"inputSchema":{
+							"type":"object",
+							"properties":{
+								"name":{"type":"string"}
+							},
+							"required":["name"]
+						},
+						"outputSchema":{
+							"type":"object",
+							"properties":{
+								"result":{"type":"string"}
+							},
+							"required":["result"]
+						},
+						"annotations":{
+							"title":"A test tool with output",
+							"readOnlyHint":true,
+							"destructiveHint":false,
+							"idempotentHint":true,
+							"openWorldHint":false,
+							"returnDirect":true
+						}
+					}"""));
+	}
+
+	@Test
+	void testToolDeserialization() throws Exception {
+		String toolJson = """
+				{
+					"name": "test-tool",
+					"description": "A test tool",
+					"inputSchema": {
+						"type": "object",
+						"properties": {
+							"name": {"type": "string"}
+						},
+						"required": ["name"]
+					},
+					"outputSchema": {
+						"type": "object",
+						"properties": {
+							"result": {"type": "string"}
+						},
+						"required": ["result"]
+					},
+					"annotations": {
+						"title": "Test Tool",
+						"readOnlyHint": true,
+						"destructiveHint": false,
+						"idempotentHint": true,
+						"openWorldHint": false,
+						"returnDirect": false
+					}
+				}
+				""";
+
+		McpSchema.Tool tool = mapper.readValue(toolJson, McpSchema.Tool.class);
+
+		assertThat(tool).isNotNull();
+		assertThat(tool.name()).isEqualTo("test-tool");
+		assertThat(tool.description()).isEqualTo("A test tool");
+		assertThat(tool.inputSchema()).isNotNull();
+		assertThat(tool.inputSchema().type()).isEqualTo("object");
+		assertThat(tool.outputSchema()).isNotNull();
+		assertThat(tool.outputSchema()).containsKey("type");
+		assertThat(tool.outputSchema().get("type")).isEqualTo("object");
+		assertThat(tool.annotations()).isNotNull();
+		assertThat(tool.annotations().title()).isEqualTo("Test Tool");
+		assertThat(tool.annotations().readOnlyHint()).isTrue();
+		assertThat(tool.annotations().idempotentHint()).isTrue();
+		assertThat(tool.annotations().destructiveHint()).isFalse();
+		assertThat(tool.annotations().returnDirect()).isFalse();
+	}
+
+	@Test
+	void testToolDeserializationWithoutOutputSchema() throws Exception {
+		String toolJson = """
+				{
+					"name": "test-tool",
+					"description": "A test tool",
+					"inputSchema": {
+						"type": "object",
+						"properties": {
+							"name": {"type": "string"}
+						},
+						"required": ["name"]
+					}
+				}
+				""";
+
+		McpSchema.Tool tool = mapper.readValue(toolJson, McpSchema.Tool.class);
+
+		assertThat(tool).isNotNull();
+		assertThat(tool.name()).isEqualTo("test-tool");
+		assertThat(tool.description()).isEqualTo("A test tool");
+		assertThat(tool.inputSchema()).isNotNull();
+		assertThat(tool.outputSchema()).isNull();
+		assertThat(tool.annotations()).isNull();
 	}
 
 	@Test
diff --git a/pom.xml b/pom.xml
index 3fd0857e8..b7a66aeec 100644
--- a/pom.xml
+++ b/pom.xml
@@ -96,6 +96,7 @@
 		4.2.0
 		7.1.0
 		4.1.0
+		1.5.7
 
 	
 

From 333a60b37e9f0c79ab1946f7ba4bed1b07a8c353 Mon Sep 17 00:00:00 2001
From: Sun Yuhan 
Date: Mon, 30 Jun 2025 20:20:21 +0800
Subject: [PATCH 011/125] cleanup: Cleaned up some unused imports. (#358)

Signed-off-by: Sun Yuhan 
---
 .../server/transport/WebFluxSseServerTransportProvider.java   | 1 -
 .../WebClientStreamableHttpAsyncClientResiliencyTests.java    | 1 -
 .../server/transport/WebMvcSseServerTransportProvider.java    | 1 -
 .../java/io/modelcontextprotocol/server/TomcatTestUtil.java   | 4 ----
 .../java/io/modelcontextprotocol/client/McpSyncClient.java    | 1 -
 .../server/transport/StdioServerTransportProvider.java        | 2 --
 .../main/java/io/modelcontextprotocol/spec/McpSession.java    | 2 --
 7 files changed, 12 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index 62264d9aa..fde067f03 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -1,7 +1,6 @@
 package io.modelcontextprotocol.server.transport;
 
 import java.io.IOException;
-import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java
index 80fc671e2..7c4d35db8 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java
@@ -1,6 +1,5 @@
 package io.modelcontextprotocol.client;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import org.junit.jupiter.api.Timeout;
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index fc86cfaa0..114eff607 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -6,7 +6,6 @@
 
 import java.io.IOException;
 import java.time.Duration;
-import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/TomcatTestUtil.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/TomcatTestUtil.java
index ccf9e2d77..8625b6a70 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/TomcatTestUtil.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/TomcatTestUtil.java
@@ -3,10 +3,6 @@
 */
 package io.modelcontextprotocol.server;
 
-import java.io.IOException;
-import java.net.InetSocketAddress;
-import java.net.ServerSocket;
-
 import org.apache.catalina.Context;
 import org.apache.catalina.startup.Tomcat;
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
index 27b020f05..83c4900d1 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
@@ -5,7 +5,6 @@
 package io.modelcontextprotocol.client;
 
 import java.time.Duration;
-import java.util.List;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
index 819da9777..9ef9c7829 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
@@ -9,9 +9,7 @@
 import java.io.InputStream;
 import java.io.InputStreamReader;
 import java.io.OutputStream;
-import java.io.Reader;
 import java.nio.charset.StandardCharsets;
-import java.util.Map;
 import java.util.concurrent.Executors;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.function.Function;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
index 473a860c2..42d170db5 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
@@ -4,8 +4,6 @@
 
 package io.modelcontextprotocol.spec;
 
-import java.util.Map;
-
 import com.fasterxml.jackson.core.type.TypeReference;
 import reactor.core.publisher.Mono;
 

From 8d71b76b21ec9179a1c4644710af08f2a33410cd Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Sun, 13 Jul 2025 15:54:55 +0200
Subject: [PATCH 012/125] refactor: reformat McpSchema.java (#392)

- Remove unused imports (CallToolResult, TextContent)
- Standardize code formatting and indentation throughout
- Adjust formatter comments positioning
- Improve readability of record definitions and builder classes
- Add comprehensive JavaDoc documentation to McpSchema

Signed-off-by: Christian Tzolov 
---
 .../modelcontextprotocol/spec/McpSchema.java  | 1902 ++++++++++-------
 1 file changed, 1125 insertions(+), 777 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 8362ca224..4a570aea0 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -11,6 +11,9 @@
 import java.util.List;
 import java.util.Map;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
@@ -21,11 +24,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
-import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.util.Assert;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 /**
  * Based on the JSON-RPC 2.0
@@ -202,254 +201,345 @@ public sealed interface JSONRPCMessage permits JSONRPCRequest, JSONRPCNotificati
 
 	}
 
+	/**
+	 * A request that expects a response.
+	 *
+	 * @param jsonrpc The JSON-RPC version (must be "2.0")
+	 * @param method The name of the method to be invoked
+	 * @param id A unique identifier for the request
+	 * @param params Parameters for the method call
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	// TODO: batching support
 	// @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
 	public record JSONRPCRequest( // @formatter:off
-						@JsonProperty("jsonrpc") String jsonrpc,
-						@JsonProperty("method") String method,
-						@JsonProperty("id") Object id,
-						@JsonProperty("params") Object params) implements JSONRPCMessage {
-		} // @formatter:on
+		@JsonProperty("jsonrpc") String jsonrpc,
+		@JsonProperty("method") String method,
+		@JsonProperty("id") Object id,
+		@JsonProperty("params") Object params) implements JSONRPCMessage { // @formatter:on
+	}
 
+	/**
+	 * A notification which does not expect a response.
+	 *
+	 * @param jsonrpc The JSON-RPC version (must be "2.0")
+	 * @param method The name of the method being notified
+	 * @param params Parameters for the notification
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	// TODO: batching support
 	// @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
 	public record JSONRPCNotification( // @formatter:off
-						@JsonProperty("jsonrpc") String jsonrpc,
-						@JsonProperty("method") String method,
-						@JsonProperty("params") Object params) implements JSONRPCMessage {
-		} // @formatter:on
+		@JsonProperty("jsonrpc") String jsonrpc,
+		@JsonProperty("method") String method,
+		@JsonProperty("params") Object params) implements JSONRPCMessage { // @formatter:on
+	}
 
+	/**
+	 * A successful (non-error) response to a request.
+	 *
+	 * @param jsonrpc The JSON-RPC version (must be "2.0")
+	 * @param id The request identifier that this response corresponds to
+	 * @param result The result of the successful request
+	 * @param error Error information if the request failed
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	// TODO: batching support
 	// @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
 	public record JSONRPCResponse( // @formatter:off
-						@JsonProperty("jsonrpc") String jsonrpc,
-						@JsonProperty("id") Object id,
-						@JsonProperty("result") Object result,
-						@JsonProperty("error") JSONRPCError error) implements JSONRPCMessage {
-
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				@JsonIgnoreProperties(ignoreUnknown = true)
-				public record JSONRPCError(
-						@JsonProperty("code") int code,
-						@JsonProperty("message") String message,
-						@JsonProperty("data") Object data) {
-				}
-		}// @formatter:on
+		@JsonProperty("jsonrpc") String jsonrpc,
+		@JsonProperty("id") Object id,
+		@JsonProperty("result") Object result,
+		@JsonProperty("error") JSONRPCError error) implements JSONRPCMessage { // @formatter:on
+
+		/**
+		 * A response to a request that indicates an error occurred.
+		 *
+		 * @param code The error type that occurred
+		 * @param message A short description of the error. The message SHOULD be limited
+		 * to a concise single sentence
+		 * @param data Additional information about the error. The value of this member is
+		 * defined by the sender (e.g. detailed error information, nested errors etc.)
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		@JsonIgnoreProperties(ignoreUnknown = true)
+		public record JSONRPCError( // @formatter:off
+			@JsonProperty("code") int code,
+			@JsonProperty("message") String message,
+			@JsonProperty("data") Object data) { // @formatter:on
+		}
+	}
 
 	// ---------------------------
 	// Initialization
 	// ---------------------------
+	/**
+	 * This request is sent from the client to the server when it first connects, asking
+	 * it to begin initialization.
+	 *
+	 * @param protocolVersion The latest version of the Model Context Protocol that the
+	 * client supports. The client MAY decide to support older versions as well
+	 * @param capabilities The capabilities that the client supports
+	 * @param clientInfo Information about the client implementation
+	 * @param meta See specification for notes on _meta usage
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record InitializeRequest( // @formatter:off
-				@JsonProperty("protocolVersion") String protocolVersion,
-				@JsonProperty("capabilities") ClientCapabilities capabilities,
-				@JsonProperty("clientInfo") Implementation clientInfo,
-				@JsonProperty("_meta") Map meta) implements Request {
-			
-			public InitializeRequest(String protocolVersion, ClientCapabilities capabilities, Implementation clientInfo) {
-				this(protocolVersion, capabilities, clientInfo, null);
-			}
-		} // @formatter:on
+		@JsonProperty("protocolVersion") String protocolVersion,
+		@JsonProperty("capabilities") ClientCapabilities capabilities,
+		@JsonProperty("clientInfo") Implementation clientInfo,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
+		public InitializeRequest(String protocolVersion, ClientCapabilities capabilities, Implementation clientInfo) {
+			this(protocolVersion, capabilities, clientInfo, null);
+		}
+	}
+
+	/**
+	 * After receiving an initialize request from the client, the server sends this
+	 * response.
+	 *
+	 * @param protocolVersion The version of the Model Context Protocol that the server
+	 * wants to use. This may not match the version that the client requested. If the
+	 * client cannot support this version, it MUST disconnect
+	 * @param capabilities The capabilities that the server supports
+	 * @param serverInfo Information about the server implementation
+	 * @param instructions Instructions describing how to use the server and its features.
+	 * This can be used by clients to improve the LLM's understanding of available tools,
+	 * resources, etc. It can be thought of like a "hint" to the model. For example, this
+	 * information MAY be added to the system prompt
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record InitializeResult( // @formatter:off
-				@JsonProperty("protocolVersion") String protocolVersion,
-				@JsonProperty("capabilities") ServerCapabilities capabilities,
-				@JsonProperty("serverInfo") Implementation serverInfo,
-				@JsonProperty("instructions") String instructions) {
-		} // @formatter:on
+		@JsonProperty("protocolVersion") String protocolVersion,
+		@JsonProperty("capabilities") ServerCapabilities capabilities,
+		@JsonProperty("serverInfo") Implementation serverInfo,
+		@JsonProperty("instructions") String instructions) { // @formatter:on
+	}
 
 	/**
-	 * Clients can implement additional features to enrich connected MCP servers with
-	 * additional capabilities. These capabilities can be used to extend the functionality
-	 * of the server, or to provide additional information to the server about the
-	 * client's capabilities.
-	 *
-	 * @param experimental WIP
-	 * @param roots define the boundaries of where servers can operate within the
-	 * filesystem, allowing them to understand which directories and files they have
-	 * access to.
-	 * @param sampling Provides a standardized way for servers to request LLM sampling
-	 * (“completions” or “generations”) from language models via clients.
-	 * @param elicitation Provides a standardized way for servers to request additional
-	 * information from users through the client during interactions.
+	 * Capabilities a client may support. Known capabilities are defined here, in this
+	 * schema, but this is not a closed set: any client can define its own, additional
+	 * capabilities.
 	 *
+	 * @param experimental Experimental, non-standard capabilities that the client
+	 * supports
+	 * @param roots Present if the client supports listing roots
+	 * @param sampling Present if the client supports sampling from an LLM
+	 * @param elicitation Present if the client supports elicitation from the server
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ClientCapabilities( // @formatter:off
-				@JsonProperty("experimental") Map experimental,
-				@JsonProperty("roots") RootCapabilities roots,
-				@JsonProperty("sampling") Sampling sampling,
-				@JsonProperty("elicitation") Elicitation elicitation) {
-
-				/**
-				 * Roots define the boundaries of where servers can operate within the filesystem,
-				 * allowing them to understand which directories and files they have access to.
-				 * Servers can request the list of roots from supporting clients and
-				 * receive notifications when that list changes.
-				 *
-				 * @param listChanged Whether the client would send notification about roots
-				 *                has changed since the last time the server checked.
-				 */
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				@JsonIgnoreProperties(ignoreUnknown = true)
-				public record RootCapabilities(
-						@JsonProperty("listChanged") Boolean listChanged) {
-				}
+		@JsonProperty("experimental") Map experimental,
+		@JsonProperty("roots") RootCapabilities roots,
+		@JsonProperty("sampling") Sampling sampling,
+		@JsonProperty("elicitation") Elicitation elicitation) { // @formatter:on
 
-				/**
-				 * Provides a standardized way for servers to request LLM
-				 * sampling ("completions" or "generations") from language
-				 * models via clients. This flow allows clients to maintain
-				 * control over model access, selection, and permissions
-				 * while enabling servers to leverage AI capabilities—with
-				 * no server API keys necessary. Servers can request text or
-				 * image-based interactions and optionally include context
-				 * from MCP servers in their prompts.
-				 */
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				public record Sampling() {
-				}
+		/**
+		 * Present if the client supports listing roots.
+		 *
+		 * @param listChanged Whether the client supports notifications for changes to the
+		 * roots list
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		@JsonIgnoreProperties(ignoreUnknown = true)
+		public record RootCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
+		}
 
-				/**
-				 * Provides a standardized way for servers to request additional
-				 * information from users through the client during interactions.
-				 * This flow allows clients to maintain control over user
-				 * interactions and data sharing while enabling servers to gather
-				 * necessary information dynamically. Servers can request structured
-				 * data from users with optional JSON schemas to validate responses.
-				 */
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				public record Elicitation() {
-				}
+		/**
+		 * Provides a standardized way for servers to request LLM sampling ("completions"
+		 * or "generations") from language models via clients. This flow allows clients to
+		 * maintain control over model access, selection, and permissions while enabling
+		 * servers to leverage AI capabilities—with no server API keys necessary. Servers
+		 * can request text or image-based interactions and optionally include context
+		 * from MCP servers in their prompts.
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		public record Sampling() {
+		}
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		/**
+		 * Provides a standardized way for servers to request additional information from
+		 * users through the client during interactions. This flow allows clients to
+		 * maintain control over user interactions and data sharing while enabling servers
+		 * to gather necessary information dynamically. Servers can request structured
+		 * data from users with optional JSON schemas to validate responses.
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		public record Elicitation() {
+		}
 
-				public static class Builder {
-						private Map experimental;
-						private RootCapabilities roots;
-						private Sampling sampling;
-						private Elicitation elicitation;
-
-						public Builder experimental(Map experimental) {
-								this.experimental = experimental;
-								return this;
-						}
-
-						public Builder roots(Boolean listChanged) {
-								this.roots = new RootCapabilities(listChanged);
-								return this;
-						}
-
-						public Builder sampling() {
-								this.sampling = new Sampling();
-								return this;
-						}
-
-						public Builder elicitation() {
-								this.elicitation = new Elicitation();
-								return this;
-						}
-
-						public ClientCapabilities build() {
-								return new ClientCapabilities(experimental, roots, sampling, elicitation);
-						}
-				}
-		}// @formatter:on
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		public static class Builder {
+
+			private Map experimental;
+
+			private RootCapabilities roots;
+
+			private Sampling sampling;
+
+			private Elicitation elicitation;
+
+			public Builder experimental(Map experimental) {
+				this.experimental = experimental;
+				return this;
+			}
+
+			public Builder roots(Boolean listChanged) {
+				this.roots = new RootCapabilities(listChanged);
+				return this;
+			}
+
+			public Builder sampling() {
+				this.sampling = new Sampling();
+				return this;
+			}
+
+			public Builder elicitation() {
+				this.elicitation = new Elicitation();
+				return this;
+			}
+
+			public ClientCapabilities build() {
+				return new ClientCapabilities(experimental, roots, sampling, elicitation);
+			}
+
+		}
+	}
 
+	/**
+	 * Capabilities that a server may support. Known capabilities are defined here, in
+	 * this schema, but this is not a closed set: any server can define its own,
+	 * additional capabilities.
+	 *
+	 * @param completions Present if the server supports argument autocompletion
+	 * suggestions
+	 * @param experimental Experimental, non-standard capabilities that the server
+	 * supports
+	 * @param logging Present if the server supports sending log messages to the client
+	 * @param prompts Present if the server offers any prompt templates
+	 * @param resources Present if the server offers any resources to read
+	 * @param tools Present if the server offers any tools to call
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ServerCapabilities( // @formatter:off
-			@JsonProperty("completions") CompletionCapabilities completions,
-				@JsonProperty("experimental") Map experimental,
-				@JsonProperty("logging") LoggingCapabilities logging,
-				@JsonProperty("prompts") PromptCapabilities prompts,
-				@JsonProperty("resources") ResourceCapabilities resources,
-				@JsonProperty("tools") ToolCapabilities tools) {
-
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				public record CompletionCapabilities() {
-				}
+		@JsonProperty("completions") CompletionCapabilities completions,
+		@JsonProperty("experimental") Map experimental,
+		@JsonProperty("logging") LoggingCapabilities logging,
+		@JsonProperty("prompts") PromptCapabilities prompts,
+		@JsonProperty("resources") ResourceCapabilities resources,
+		@JsonProperty("tools") ToolCapabilities tools) { // @formatter:on
 
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				public record LoggingCapabilities() {
-				}
+		/**
+		 * Present if the server supports argument autocompletion suggestions.
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		public record CompletionCapabilities() {
+		}
 
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				public record PromptCapabilities(
-						@JsonProperty("listChanged") Boolean listChanged) {
-				}
+		/**
+		 * Present if the server supports sending log messages to the client.
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		public record LoggingCapabilities() {
+		}
 
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				public record ResourceCapabilities(
-						@JsonProperty("subscribe") Boolean subscribe,
-						@JsonProperty("listChanged") Boolean listChanged) {
-				}
+		/**
+		 * Present if the server offers any prompt templates.
+		 *
+		 * @param listChanged Whether this server supports notifications for changes to
+		 * the prompt list
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		public record PromptCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
+		}
 
-				@JsonInclude(JsonInclude.Include.NON_ABSENT)
-				public record ToolCapabilities(
-						@JsonProperty("listChanged") Boolean listChanged) {
-				}
+		/**
+		 * Present if the server offers any resources to read.
+		 *
+		 * @param subscribe Whether this server supports subscribing to resource updates
+		 * @param listChanged Whether this server supports notifications for changes to
+		 * the resource list
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		public record ResourceCapabilities(@JsonProperty("subscribe") Boolean subscribe,
+				@JsonProperty("listChanged") Boolean listChanged) {
+		}
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		/**
+		 * Present if the server offers any tools to call.
+		 *
+		 * @param listChanged Whether this server supports notifications for changes to
+		 * the tool list
+		 */
+		@JsonInclude(JsonInclude.Include.NON_ABSENT)
+		public record ToolCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
+		}
 
-				public static class Builder {
-
-						private CompletionCapabilities completions;
-						private Map experimental;
-						private LoggingCapabilities logging = new LoggingCapabilities();
-						private PromptCapabilities prompts;
-						private ResourceCapabilities resources;
-						private ToolCapabilities tools;
-
-						public Builder completions() {
-								this.completions = new CompletionCapabilities();
-								return this;
-						}
-
-						public Builder experimental(Map experimental) {
-								this.experimental = experimental;
-								return this;
-						}
-
-						public Builder logging() {
-								this.logging = new LoggingCapabilities();
-								return this;
-						}
-
-						public Builder prompts(Boolean listChanged) {
-								this.prompts = new PromptCapabilities(listChanged);
-								return this;
-						}
-
-						public Builder resources(Boolean subscribe, Boolean listChanged) {
-								this.resources = new ResourceCapabilities(subscribe, listChanged);
-								return this;
-						}
-
-						public Builder tools(Boolean listChanged) {
-								this.tools = new ToolCapabilities(listChanged);
-								return this;
-						}
-
-						public ServerCapabilities build() {
-								return new ServerCapabilities(completions, experimental, logging, prompts, resources, tools);
-						}
-				}
-		} // @formatter:on
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		public static class Builder {
+
+			private CompletionCapabilities completions;
+
+			private Map experimental;
+
+			private LoggingCapabilities logging = new LoggingCapabilities();
+
+			private PromptCapabilities prompts;
+
+			private ResourceCapabilities resources;
+
+			private ToolCapabilities tools;
+
+			public Builder completions() {
+				this.completions = new CompletionCapabilities();
+				return this;
+			}
+
+			public Builder experimental(Map experimental) {
+				this.experimental = experimental;
+				return this;
+			}
+
+			public Builder logging() {
+				this.logging = new LoggingCapabilities();
+				return this;
+			}
+
+			public Builder prompts(Boolean listChanged) {
+				this.prompts = new PromptCapabilities(listChanged);
+				return this;
+			}
+
+			public Builder resources(Boolean subscribe, Boolean listChanged) {
+				this.resources = new ResourceCapabilities(subscribe, listChanged);
+				return this;
+			}
+
+			public Builder tools(Boolean listChanged) {
+				this.tools = new ToolCapabilities(listChanged);
+				return this;
+			}
+
+			public ServerCapabilities build() {
+				return new ServerCapabilities(completions, experimental, logging, prompts, resources, tools);
+			}
+
+		}
+	}
 
 	/**
 	 * Describes the name and version of an MCP implementation, with an optional title for
@@ -462,10 +552,10 @@ public ServerCapabilities build() {
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record Implementation(// @formatter:off
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title,
-				@JsonProperty("version") String version) implements BaseMetadata {// @formatter:on			
+	public record Implementation( // @formatter:off
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title,
+		@JsonProperty("version") String version) implements BaseMetadata { // @formatter:on			
 
 		public Implementation(String name, String version) {
 			this(name, null, version);
@@ -473,11 +563,12 @@ public Implementation(String name, String version) {
 	}
 
 	// Existing Enums and Base Types (from previous implementation)
-	public enum Role {// @formatter:off
+	public enum Role {
 
-				@JsonProperty("user") USER,
-				@JsonProperty("assistant") ASSISTANT
-		}// @formatter:on
+	// @formatter:off
+		@JsonProperty("user") USER,
+		@JsonProperty("assistant") ASSISTANT
+	} // @formatter:on
 
 	// ---------------------------
 	// Resource Interfaces
@@ -507,9 +598,9 @@ public interface Annotated {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record Annotations( // @formatter:off
-				@JsonProperty("audience") List audience,
-				@JsonProperty("priority") Double priority) {
-		} // @formatter:on
+		@JsonProperty("audience") List audience,
+		@JsonProperty("priority") Double priority) { // @formatter:on
+	}
 
 	/**
 	 * A common interface for resource content, which includes metadata about the resource
@@ -573,13 +664,13 @@ public interface BaseMetadata {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record Resource( // @formatter:off
-				@JsonProperty("uri") String uri,
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title,
-				@JsonProperty("description") String description,
-				@JsonProperty("mimeType") String mimeType,
-				@JsonProperty("size") Long size,
-				@JsonProperty("annotations") Annotations annotations) implements Annotated, ResourceContent {// @formatter:on
+		@JsonProperty("uri") String uri,
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title,
+		@JsonProperty("description") String description,
+		@JsonProperty("mimeType") String mimeType,
+		@JsonProperty("size") Long size,
+		@JsonProperty("annotations") Annotations annotations) implements Annotated, ResourceContent { // @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -685,12 +776,12 @@ public Resource build() {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ResourceTemplate( // @formatter:off
-				@JsonProperty("uriTemplate") String uriTemplate,
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title,
-				@JsonProperty("description") String description,
-				@JsonProperty("mimeType") String mimeType,
-				@JsonProperty("annotations") Annotations annotations) implements Annotated, BaseMetadata {// @formatter:on
+		@JsonProperty("uriTemplate") String uriTemplate,
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title,
+		@JsonProperty("description") String description,
+		@JsonProperty("mimeType") String mimeType,
+		@JsonProperty("annotations") Annotations annotations) implements Annotated, BaseMetadata { // @formatter:on
 
 		public ResourceTemplate(String uriTemplate, String name, String description, String mimeType,
 				Annotations annotations) {
@@ -698,36 +789,61 @@ public ResourceTemplate(String uriTemplate, String name, String description, Str
 		}
 	}
 
+	/**
+	 * The server's response to a resources/list request from the client.
+	 *
+	 * @param resources A list of resources that the server provides
+	 * @param nextCursor An opaque token representing the pagination position after the
+	 * last returned result. If present, there may be more results available
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListResourcesResult( // @formatter:off
-				@JsonProperty("resources") List resources,
-				@JsonProperty("nextCursor") String nextCursor) {
-		} // @formatter:on
+		@JsonProperty("resources") List resources,
+		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+	}
 
+	/**
+	 * The server's response to a resources/templates/list request from the client.
+	 *
+	 * @param resourceTemplates A list of resource templates that the server provides
+	 * @param nextCursor An opaque token representing the pagination position after the
+	 * last returned result. If present, there may be more results available
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListResourceTemplatesResult( // @formatter:off
-				@JsonProperty("resourceTemplates") List resourceTemplates,
-				@JsonProperty("nextCursor") String nextCursor) {
-		} // @formatter:on
+		@JsonProperty("resourceTemplates") List resourceTemplates,
+		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+	}
 
+	/**
+	 * Sent from the client to the server, to read a specific resource URI.
+	 *
+	 * @param uri The URI of the resource to read. The URI can use any protocol; it is up
+	 * to the server how to interpret it
+	 * @param meta See specification for notes on _meta usage
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ReadResourceRequest( // @formatter:off
-				@JsonProperty("uri") String uri,
-				@JsonProperty("_meta") Map meta) implements Request {// @formatter:on
+		@JsonProperty("uri") String uri,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
 		public ReadResourceRequest(String uri) {
 			this(uri, null);
 		}
 	}
 
+	/**
+	 * The server's response to a resources/read request from the client.
+	 *
+	 * @param contents The contents of the resource
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ReadResourceResult( // @formatter:off
-				@JsonProperty("contents") List contents){
-		} // @formatter:on
+	public record ReadResourceResult(@JsonProperty("contents") List contents) {
+	}
 
 	/**
 	 * Sent from the client to request resources/updated notifications from the server
@@ -738,15 +854,19 @@ public record ReadResourceResult( // @formatter:off
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record SubscribeRequest( // @formatter:off
-				@JsonProperty("uri") String uri){
-		} // @formatter:on
+	public record SubscribeRequest(@JsonProperty("uri") String uri) {
+	}
 
+	/**
+	 * Sent from the client to request cancellation of resources/updated notifications
+	 * from the server. This should follow a previous resources/subscribe request.
+	 *
+	 * @param uri The URI of the resource to unsubscribe from
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record UnsubscribeRequest( // @formatter:off
-				@JsonProperty("uri") String uri){
-		} // @formatter:on
+	public record UnsubscribeRequest(@JsonProperty("uri") String uri) {
+	}
 
 	/**
 	 * The contents of a specific resource or sub-resource.
@@ -781,10 +901,10 @@ public sealed interface ResourceContents permits TextResourceContents, BlobResou
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record TextResourceContents( // @formatter:off
-				@JsonProperty("uri") String uri,
-				@JsonProperty("mimeType") String mimeType,
-				@JsonProperty("text") String text) implements ResourceContents {
-		} // @formatter:on
+		@JsonProperty("uri") String uri,
+		@JsonProperty("mimeType") String mimeType,
+		@JsonProperty("text") String text) implements ResourceContents { // @formatter:on
+	}
 
 	/**
 	 * Binary contents of a resource.
@@ -798,10 +918,10 @@ public record TextResourceContents( // @formatter:off
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record BlobResourceContents( // @formatter:off
-				@JsonProperty("uri") String uri,
-				@JsonProperty("mimeType") String mimeType,
-				@JsonProperty("blob") String blob) implements ResourceContents {
-		} // @formatter:on
+		@JsonProperty("uri") String uri,
+		@JsonProperty("mimeType") String mimeType,
+		@JsonProperty("blob") String blob) implements ResourceContents { // @formatter:on
+	}
 
 	// ---------------------------
 	// Prompt Interfaces
@@ -817,10 +937,10 @@ public record BlobResourceContents( // @formatter:off
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record Prompt( // @formatter:off
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title,
-				@JsonProperty("description") String description,
-				@JsonProperty("arguments") List arguments) implements BaseMetadata { // @formatter:on
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title,
+		@JsonProperty("description") String description,
+		@JsonProperty("arguments") List arguments) implements BaseMetadata { // @formatter:on
 
 		public Prompt(String name, String description, List arguments) {
 			this(name, null, description, arguments != null ? arguments : new ArrayList<>());
@@ -838,10 +958,10 @@ public Prompt(String name, String description, List arguments) {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record PromptArgument( // @formatter:off
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title,
-				@JsonProperty("description") String description,
-				@JsonProperty("required") Boolean required) implements BaseMetadata {// @formatter:on
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title,
+		@JsonProperty("description") String description,
+		@JsonProperty("required") Boolean required) implements BaseMetadata { // @formatter:on
 
 		public PromptArgument(String name, String description, Boolean required) {
 			this(name, null, description, required);
@@ -860,9 +980,9 @@ public PromptArgument(String name, String description, Boolean required) {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record PromptMessage( // @formatter:off
-				@JsonProperty("role") Role role,
-				@JsonProperty("content") Content content) {
-		} // @formatter:on
+		@JsonProperty("role") Role role,
+		@JsonProperty("content") Content content) { // @formatter:on
+	}
 
 	/**
 	 * The server's response to a prompts/list request from the client.
@@ -874,9 +994,9 @@ public record PromptMessage( // @formatter:off
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListPromptsResult( // @formatter:off
-				@JsonProperty("prompts") List prompts,
-				@JsonProperty("nextCursor") String nextCursor) {
-		}// @formatter:on
+		@JsonProperty("prompts") List prompts,
+		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+	}
 
 	/**
 	 * Used by the client to get a prompt provided by the server.
@@ -886,28 +1006,28 @@ public record ListPromptsResult( // @formatter:off
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record GetPromptRequest(// @formatter:off
-				@JsonProperty("name") String name,
-				@JsonProperty("arguments") Map arguments,
-				@JsonProperty("_meta") Map meta) implements Request {
+	public record GetPromptRequest( // @formatter:off
+		@JsonProperty("name") String name,
+		@JsonProperty("arguments") Map arguments,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
-				public GetPromptRequest(String name, Map arguments) {
-						this(name, arguments, null);
-				}
-		}// @formatter:off
+		public GetPromptRequest(String name, Map arguments) {
+			this(name, arguments, null);
+		}
+	}
 
-		/**
-		 * The server's response to a prompts/get request from the client.
-		 *
-		 * @param description An optional description for the prompt.
-		 * @param messages A list of messages to display as part of the prompt.
-		 */
-		@JsonInclude(JsonInclude.Include.NON_ABSENT)
-		@JsonIgnoreProperties(ignoreUnknown = true)
-		public record GetPromptResult( // @formatter:off
-				@JsonProperty("description") String description,
-				@JsonProperty("messages") List messages) {
-		} // @formatter:on
+	/**
+	 * The server's response to a prompts/get request from the client.
+	 *
+	 * @param description An optional description for the prompt.
+	 * @param messages A list of messages to display as part of the prompt.
+	 */
+	@JsonInclude(JsonInclude.Include.NON_ABSENT)
+	@JsonIgnoreProperties(ignoreUnknown = true)
+	public record GetPromptResult( // @formatter:off
+		@JsonProperty("description") String description,
+		@JsonProperty("messages") List messages) { // @formatter:on
+	}
 
 	// ---------------------------
 	// Tool Interfaces
@@ -922,20 +1042,30 @@ public record GetPromptResult( // @formatter:off
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListToolsResult( // @formatter:off
-				@JsonProperty("tools") List tools,
-				@JsonProperty("nextCursor") String nextCursor) {
-		}// @formatter:on
+		@JsonProperty("tools") List tools,
+		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+	}
 
+	/**
+	 * A JSON Schema object that describes the expected structure of arguments or output.
+	 *
+	 * @param type The type of the schema (e.g., "object")
+	 * @param properties The properties of the schema object
+	 * @param required List of required property names
+	 * @param additionalProperties Whether additional properties are allowed
+	 * @param defs Schema definitions using the newer $defs keyword
+	 * @param definitions Schema definitions using the legacy definitions keyword
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record JsonSchema( // @formatter:off
-				@JsonProperty("type") String type,
-				@JsonProperty("properties") Map properties,
-				@JsonProperty("required") List required,
-				@JsonProperty("additionalProperties") Boolean additionalProperties,
-				@JsonProperty("$defs") Map defs,
-				@JsonProperty("definitions") Map definitions) {
-		} // @formatter:on
+		@JsonProperty("type") String type,
+		@JsonProperty("properties") Map properties,
+		@JsonProperty("required") List required,
+		@JsonProperty("additionalProperties") Boolean additionalProperties,
+		@JsonProperty("$defs") Map defs,
+		@JsonProperty("definitions") Map definitions) { // @formatter:on
+	}
 
 	/**
 	 * Additional properties describing a Tool to clients.
@@ -955,8 +1085,8 @@ public record ToolAnnotations( // @formatter:off
 		@JsonProperty("destructiveHint") Boolean destructiveHint,
 		@JsonProperty("idempotentHint") Boolean idempotentHint,
 		@JsonProperty("openWorldHint") Boolean openWorldHint,
-		@JsonProperty("returnDirect") Boolean returnDirect) {
-	} // @formatter:on
+		@JsonProperty("returnDirect") Boolean returnDirect) { // @formatter:on
+	}
 
 	/**
 	 * Represents a tool that the server provides. Tools enable servers to expose
@@ -982,7 +1112,7 @@ public record Tool( // @formatter:off
 		@JsonProperty("description") String description,
 		@JsonProperty("inputSchema") JsonSchema inputSchema,
 		@JsonProperty("outputSchema") Map outputSchema,
-		@JsonProperty("annotations") ToolAnnotations annotations) {// @formatter:on
+		@JsonProperty("annotations") ToolAnnotations annotations) { // @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -1115,96 +1245,102 @@ private static JsonSchema parseSchema(String schema) {
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record CallToolRequest(// @formatter:off
-				@JsonProperty("name") String name,
-				@JsonProperty("arguments") Map arguments,
-				@JsonProperty("_meta") Map meta) implements Request {// @formatter:off
+	public record CallToolRequest( // @formatter:off
+		@JsonProperty("name") String name,
+		@JsonProperty("arguments") Map arguments,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
-				public CallToolRequest(String name, String jsonArguments) {
-						this(name, parseJsonArguments(jsonArguments), null);
-				}
-				public CallToolRequest(String name, Map arguments) {
-						this(name, arguments, null);
-				}
+		public CallToolRequest(String name, String jsonArguments) {
+			this(name, parseJsonArguments(jsonArguments), null);
+		}
 
-				private static Map parseJsonArguments(String jsonArguments) {
-						try {
-								return OBJECT_MAPPER.readValue(jsonArguments, MAP_TYPE_REF);
-						}
-						catch (IOException e) {
-								throw new IllegalArgumentException("Invalid arguments: " + jsonArguments, e);
-						}
-				}
+		public CallToolRequest(String name, Map arguments) {
+			this(name, arguments, null);
+		}
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		private static Map parseJsonArguments(String jsonArguments) {
+			try {
+				return OBJECT_MAPPER.readValue(jsonArguments, MAP_TYPE_REF);
+			}
+			catch (IOException e) {
+				throw new IllegalArgumentException("Invalid arguments: " + jsonArguments, e);
+			}
+		}
 
-				public static class Builder {
-						private String name;
-						private Map arguments;
-						private Map meta;
-
-						public Builder name(String name) {
-								this.name = name;
-								return this;
-						}
-
-						public Builder arguments(Map arguments) {
-								this.arguments = arguments;
-								return this;
-						}
-
-						public Builder arguments(String jsonArguments) {
-								this.arguments = parseJsonArguments(jsonArguments);
-								return this;
-						}
-
-						public Builder meta(Map meta) {
-								this.meta = meta;
-								return this;
-						}
-
-						public Builder progressToken(String progressToken) {
-								if (this.meta == null) {
-										this.meta = new HashMap<>();
-								}
-								this.meta.put("progressToken", progressToken);
-								return this;
-						}
-
-						public CallToolRequest build() {
-								Assert.hasText(name, "name must not be empty");
-								return new CallToolRequest(name, arguments, meta);
-						}
-				}
+		public static Builder builder() {
+			return new Builder();
 		}
 
-		/**
-		 * The server's response to a tools/call request from the client.
-		 *
-		 * @param content A list of content items representing the tool's output. Each item can be text, an image,
-		 *                or an embedded resource.
-		 * @param isError If true, indicates that the tool execution failed and the content contains error information.
-		 *                If false or absent, indicates successful execution.
-		 * @param structuredContent An optional JSON object that represents the structured result of the tool call.
-		 */
-		@JsonInclude(JsonInclude.Include.NON_ABSENT)
-		@JsonIgnoreProperties(ignoreUnknown = true)
-		public record CallToolResult( // @formatter:off
-				@JsonProperty("content") List content,
-				@JsonProperty("isError") Boolean isError,
-				@JsonProperty("structuredContent") Map structuredContent) {// @formatter:on
+		public static class Builder {
 
-		// backwards compatibility constructor
-		public CallToolResult(List content, Boolean isError) {
-			this(content, isError, null);
-		}
+			private String name;
 
-		/**
-		 * Creates a new instance of {@link CallToolResult} with a string containing the
-		 * tool result.
-		 * @param content The content of the tool result. This will be mapped to a
+			private Map arguments;
+
+			private Map meta;
+
+			public Builder name(String name) {
+				this.name = name;
+				return this;
+			}
+
+			public Builder arguments(Map arguments) {
+				this.arguments = arguments;
+				return this;
+			}
+
+			public Builder arguments(String jsonArguments) {
+				this.arguments = parseJsonArguments(jsonArguments);
+				return this;
+			}
+
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
+			public Builder progressToken(String progressToken) {
+				if (this.meta == null) {
+					this.meta = new HashMap<>();
+				}
+				this.meta.put("progressToken", progressToken);
+				return this;
+			}
+
+			public CallToolRequest build() {
+				Assert.hasText(name, "name must not be empty");
+				return new CallToolRequest(name, arguments, meta);
+			}
+
+		}
+	}
+
+	/**
+	 * The server's response to a tools/call request from the client.
+	 *
+	 * @param content A list of content items representing the tool's output. Each item
+	 * can be text, an image, or an embedded resource.
+	 * @param isError If true, indicates that the tool execution failed and the content
+	 * contains error information. If false or absent, indicates successful execution.
+	 * @param structuredContent An optional JSON object that represents the structured
+	 * result of the tool call.
+	 */
+	@JsonInclude(JsonInclude.Include.NON_ABSENT)
+	@JsonIgnoreProperties(ignoreUnknown = true)
+	public record CallToolResult( // @formatter:off
+		@JsonProperty("content") List content,
+		@JsonProperty("isError") Boolean isError,
+		@JsonProperty("structuredContent") Map structuredContent) { // @formatter:on
+
+		// backwards compatibility constructor
+		public CallToolResult(List content, Boolean isError) {
+			this(content, isError, null);
+		}
+
+		/**
+		 * Creates a new instance of {@link CallToolResult} with a string containing the
+		 * tool result.
+		 * @param content The content of the tool result. This will be mapped to a
 		 * one-sized list with a {@link TextContent} element.
 		 * @param isError If true, indicates that the tool execution failed and the
 		 * content contains error information. If false or absent, indicates successful
@@ -1322,58 +1458,91 @@ public CallToolResult build() {
 	// ---------------------------
 	// Sampling Interfaces
 	// ---------------------------
+	/**
+	 * The server's preferences for model selection, requested of the client during
+	 * sampling.
+	 *
+	 * @param hints Optional hints to use for model selection. If multiple hints are
+	 * specified, the client MUST evaluate them in order (such that the first match is
+	 * taken). The client SHOULD prioritize these hints over the numeric priorities, but
+	 * MAY still use the priorities to select from ambiguous matches
+	 * @param costPriority How much to prioritize cost when selecting a model. A value of
+	 * 0 means cost is not important, while a value of 1 means cost is the most important
+	 * factor
+	 * @param speedPriority How much to prioritize sampling speed (latency) when selecting
+	 * a model. A value of 0 means speed is not important, while a value of 1 means speed
+	 * is the most important factor
+	 * @param intelligencePriority How much to prioritize intelligence and capabilities
+	 * when selecting a model. A value of 0 means intelligence is not important, while a
+	 * value of 1 means intelligence is the most important factor
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ModelPreferences(// @formatter:off
+	public record ModelPreferences( // @formatter:off
 		@JsonProperty("hints") List hints,
 		@JsonProperty("costPriority") Double costPriority,
 		@JsonProperty("speedPriority") Double speedPriority,
-		@JsonProperty("intelligencePriority") Double intelligencePriority) {
+		@JsonProperty("intelligencePriority") Double intelligencePriority) { // @formatter:on
 
 		public static Builder builder() {
-				return new Builder();
+			return new Builder();
 		}
 
 		public static class Builder {
-				private List hints;
-				private Double costPriority;
-				private Double speedPriority;
-				private Double intelligencePriority;
-
-				public Builder hints(List hints) {
-						this.hints = hints;
-						return this;
-				}
 
-				public Builder addHint(String name) {
-						if (this.hints == null) {
-								this.hints = new ArrayList<>();
-						}
-						this.hints.add(new ModelHint(name));
-						return this;
-				}
+			private List hints;
 
-				public Builder costPriority(Double costPriority) {
-						this.costPriority = costPriority;
-						return this;
-				}
+			private Double costPriority;
 
-				public Builder speedPriority(Double speedPriority) {
-						this.speedPriority = speedPriority;
-						return this;
-				}
+			private Double speedPriority;
 
-				public Builder intelligencePriority(Double intelligencePriority) {
-						this.intelligencePriority = intelligencePriority;
-						return this;
-				}
+			private Double intelligencePriority;
+
+			public Builder hints(List hints) {
+				this.hints = hints;
+				return this;
+			}
 
-				public ModelPreferences build() {
-						return new ModelPreferences(hints, costPriority, speedPriority, intelligencePriority);
+			public Builder addHint(String name) {
+				if (this.hints == null) {
+					this.hints = new ArrayList<>();
 				}
+				this.hints.add(new ModelHint(name));
+				return this;
+			}
+
+			public Builder costPriority(Double costPriority) {
+				this.costPriority = costPriority;
+				return this;
+			}
+
+			public Builder speedPriority(Double speedPriority) {
+				this.speedPriority = speedPriority;
+				return this;
+			}
+
+			public Builder intelligencePriority(Double intelligencePriority) {
+				this.intelligencePriority = intelligencePriority;
+				return this;
+			}
+
+			public ModelPreferences build() {
+				return new ModelPreferences(hints, costPriority, speedPriority, intelligencePriority);
+			}
+
 		}
-	} // @formatter:on
+	}
 
+	/**
+	 * Hints to use for model selection.
+	 *
+	 * @param name A hint for a model name. The client SHOULD treat this as a substring of
+	 * a model name; for example: `claude-3-5-sonnet` should match
+	 * `claude-3-5-sonnet-20241022`, `sonnet` should match `claude-3-5-sonnet-20241022`,
+	 * `claude-3-sonnet-20240229`, etc., `claude` should match any Claude model. The
+	 * client MAY also map the string to a different provider's model name or a different
+	 * model family, as long as it fills a similar niche
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ModelHint(@JsonProperty("name") String name) {
@@ -1382,289 +1551,374 @@ public static ModelHint of(String name) {
 		}
 	}
 
+	/**
+	 * Describes a message issued to or received from an LLM API.
+	 *
+	 * @param role The sender or recipient of messages and data in a conversation
+	 * @param content The content of the message
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record SamplingMessage(// @formatter:off
-				@JsonProperty("role") Role role,
-				@JsonProperty("content") Content content) {
-		} // @formatter:on
+	public record SamplingMessage( // @formatter:off
+		@JsonProperty("role") Role role,
+		@JsonProperty("content") Content content) { // @formatter:on
+	}
 
-	// Sampling and Message Creation
+	/**
+	 * A request from the server to sample an LLM via the client. The client has full
+	 * discretion over which model to select. The client should also inform the user
+	 * before beginning sampling, to allow them to inspect the request (human in the loop)
+	 * and decide whether to approve it.
+	 *
+	 * @param messages The conversation messages to send to the LLM
+	 * @param modelPreferences The server's preferences for which model to select. The
+	 * client MAY ignore these preferences
+	 * @param systemPrompt An optional system prompt the server wants to use for sampling.
+	 * The client MAY modify or omit this prompt
+	 * @param includeContext A request to include context from one or more MCP servers
+	 * (including the caller), to be attached to the prompt. The client MAY ignore this
+	 * request
+	 * @param temperature Optional temperature parameter for sampling
+	 * @param maxTokens The maximum number of tokens to sample, as requested by the
+	 * server. The client MAY choose to sample fewer tokens than requested
+	 * @param stopSequences Optional stop sequences for sampling
+	 * @param metadata Optional metadata to pass through to the LLM provider. The format
+	 * of this metadata is provider-specific
+	 * @param meta See specification for notes on _meta usage
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record CreateMessageRequest(// @formatter:off
-				@JsonProperty("messages") List messages,
-				@JsonProperty("modelPreferences") ModelPreferences modelPreferences,
-				@JsonProperty("systemPrompt") String systemPrompt,
-				@JsonProperty("includeContext") ContextInclusionStrategy includeContext,
-				@JsonProperty("temperature") Double temperature,
-				@JsonProperty("maxTokens") int maxTokens,
-				@JsonProperty("stopSequences") List stopSequences,
-				@JsonProperty("metadata") Map metadata,
-				@JsonProperty("_meta") Map meta) implements Request {
-
-				
-				// backwards compatibility constructor
-				public CreateMessageRequest(List messages, ModelPreferences modelPreferences,
-											String systemPrompt, ContextInclusionStrategy includeContext,
-											Double temperature, int maxTokens, List stopSequences,
-											Map metadata) {
-						this(messages, modelPreferences, systemPrompt, includeContext, temperature, maxTokens,
-								stopSequences, metadata, null);
-				}
+	public record CreateMessageRequest( // @formatter:off
+		@JsonProperty("messages") List messages,
+		@JsonProperty("modelPreferences") ModelPreferences modelPreferences,
+		@JsonProperty("systemPrompt") String systemPrompt,
+		@JsonProperty("includeContext") ContextInclusionStrategy includeContext,
+		@JsonProperty("temperature") Double temperature,
+		@JsonProperty("maxTokens") int maxTokens,
+		@JsonProperty("stopSequences") List stopSequences,
+		@JsonProperty("metadata") Map metadata,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
-				public enum ContextInclusionStrategy {
-						@JsonProperty("none") NONE,
-						@JsonProperty("thisServer") THIS_SERVER,
-						@JsonProperty("allServers") ALL_SERVERS
-				}
+		// backwards compatibility constructor
+		public CreateMessageRequest(List messages, ModelPreferences modelPreferences,
+				String systemPrompt, ContextInclusionStrategy includeContext, Double temperature, int maxTokens,
+				List stopSequences, Map metadata) {
+			this(messages, modelPreferences, systemPrompt, includeContext, temperature, maxTokens, stopSequences,
+					metadata, null);
+		}
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		public enum ContextInclusionStrategy {
+
+		// @formatter:off
+			@JsonProperty("none") NONE,
+			@JsonProperty("thisServer") THIS_SERVER,
+			@JsonProperty("allServers")ALL_SERVERS
+		} // @formatter:on
+
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		public static class Builder {
+
+			private List messages;
+
+			private ModelPreferences modelPreferences;
+
+			private String systemPrompt;
+
+			private ContextInclusionStrategy includeContext;
+
+			private Double temperature;
+
+			private int maxTokens;
+
+			private List stopSequences;
+
+			private Map metadata;
+
+			private Map meta;
+
+			public Builder messages(List messages) {
+				this.messages = messages;
+				return this;
+			}
+
+			public Builder modelPreferences(ModelPreferences modelPreferences) {
+				this.modelPreferences = modelPreferences;
+				return this;
+			}
 
-				public static class Builder {
-						private List messages;
-						private ModelPreferences modelPreferences;
-						private String systemPrompt;
-						private ContextInclusionStrategy includeContext;
-						private Double temperature;
-						private int maxTokens;
-						private List stopSequences;
-						private Map metadata;
-						private Map meta;
-
-						public Builder messages(List messages) {
-								this.messages = messages;
-								return this;
-						}
-
-						public Builder modelPreferences(ModelPreferences modelPreferences) {
-								this.modelPreferences = modelPreferences;
-								return this;
-						}
-
-						public Builder systemPrompt(String systemPrompt) {
-								this.systemPrompt = systemPrompt;
-								return this;
-						}
-
-						public Builder includeContext(ContextInclusionStrategy includeContext) {
-								this.includeContext = includeContext;
-								return this;
-						}
-
-						public Builder temperature(Double temperature) {
-								this.temperature = temperature;
-								return this;
-						}
-
-						public Builder maxTokens(int maxTokens) {
-								this.maxTokens = maxTokens;
-								return this;
-						}
-
-						public Builder stopSequences(List stopSequences) {
-								this.stopSequences = stopSequences;
-								return this;
-						}
-
-						public Builder metadata(Map metadata) {
-								this.metadata = metadata;
-								return this;
-						}
-
-						public Builder meta(Map meta) {
-								this.meta = meta;
-								return this;
-						}
-
-						public Builder progressToken(String progressToken) {
-								if (this.meta == null) {
-										this.meta = new HashMap<>();
-								}
-								this.meta.put("progressToken", progressToken);
-								return this;
-						}
-
-						public CreateMessageRequest build() {
-								return new CreateMessageRequest(messages, modelPreferences, systemPrompt,
-										includeContext, temperature, maxTokens, stopSequences, metadata, meta);
-						}
+			public Builder systemPrompt(String systemPrompt) {
+				this.systemPrompt = systemPrompt;
+				return this;
+			}
+
+			public Builder includeContext(ContextInclusionStrategy includeContext) {
+				this.includeContext = includeContext;
+				return this;
+			}
+
+			public Builder temperature(Double temperature) {
+				this.temperature = temperature;
+				return this;
+			}
+
+			public Builder maxTokens(int maxTokens) {
+				this.maxTokens = maxTokens;
+				return this;
+			}
+
+			public Builder stopSequences(List stopSequences) {
+				this.stopSequences = stopSequences;
+				return this;
+			}
+
+			public Builder metadata(Map metadata) {
+				this.metadata = metadata;
+				return this;
+			}
+
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
+			public Builder progressToken(String progressToken) {
+				if (this.meta == null) {
+					this.meta = new HashMap<>();
 				}
-		}// @formatter:on
+				this.meta.put("progressToken", progressToken);
+				return this;
+			}
+
+			public CreateMessageRequest build() {
+				return new CreateMessageRequest(messages, modelPreferences, systemPrompt, includeContext, temperature,
+						maxTokens, stopSequences, metadata, meta);
+			}
+
+		}
+	}
 
+	/**
+	 * The client's response to a sampling/create_message request from the server. The
+	 * client should inform the user before returning the sampled message, to allow them
+	 * to inspect the response (human in the loop) and decide whether to allow the server
+	 * to see it.
+	 *
+	 * @param role The role of the message sender (typically assistant)
+	 * @param content The content of the sampled message
+	 * @param model The name of the model that generated the message
+	 * @param stopReason The reason why sampling stopped, if known
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record CreateMessageResult(// @formatter:off
-				@JsonProperty("role") Role role,
-				@JsonProperty("content") Content content,
-				@JsonProperty("model") String model,
-				@JsonProperty("stopReason") StopReason stopReason) {
-
-				public enum StopReason {
-						@JsonProperty("endTurn") END_TURN("endTurn"),
-						@JsonProperty("stopSequence") STOP_SEQUENCE("stopSequence"),
-						@JsonProperty("maxTokens") MAX_TOKENS("maxTokens"),
-						@JsonProperty("unknown") UNKNOWN("unknown");
-
-						private final String value;
-
-						StopReason(String value) {
-								this.value = value;
-						}
-
-						@JsonCreator
-						private static StopReason of(String value) {
-								return Arrays.stream(StopReason.values())
-												.filter(stopReason -> stopReason.value.equals(value))
-												.findFirst()
-												.orElse(StopReason.UNKNOWN);
-						}
-				}
+	public record CreateMessageResult( // @formatter:off
+		@JsonProperty("role") Role role,
+		@JsonProperty("content") Content content,
+		@JsonProperty("model") String model,
+		@JsonProperty("stopReason") StopReason stopReason) { // @formatter:on
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		public enum StopReason {
 
-				public static class Builder {
-						private Role role = Role.ASSISTANT;
-						private Content content;
-						private String model;
-						private StopReason stopReason = StopReason.END_TURN;
-
-						public Builder role(Role role) {
-								this.role = role;
-								return this;
-						}
-
-						public Builder content(Content content) {
-								this.content = content;
-								return this;
-						}
-
-						public Builder model(String model) {
-								this.model = model;
-								return this;
-						}
-
-						public Builder stopReason(StopReason stopReason) {
-								this.stopReason = stopReason;
-								return this;
-						}
-
-						public Builder message(String message) {
-								this.content = new TextContent(message);
-								return this;
-						}
-
-						public CreateMessageResult build() {
-								return new CreateMessageResult(role, content, model, stopReason);
-						}
-				}
-		}// @formatter:on
+		// @formatter:off
+			@JsonProperty("endTurn") END_TURN("endTurn"),
+			@JsonProperty("stopSequence") STOP_SEQUENCE("stopSequence"),
+			@JsonProperty("maxTokens") MAX_TOKENS("maxTokens"),
+			@JsonProperty("unknown") UNKNOWN("unknown");
+			// @formatter:on
+
+			private final String value;
+
+			StopReason(String value) {
+				this.value = value;
+			}
+
+			@JsonCreator
+			private static StopReason of(String value) {
+				return Arrays.stream(StopReason.values())
+					.filter(stopReason -> stopReason.value.equals(value))
+					.findFirst()
+					.orElse(StopReason.UNKNOWN);
+			}
+
+		}
+
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		public static class Builder {
+
+			private Role role = Role.ASSISTANT;
+
+			private Content content;
+
+			private String model;
+
+			private StopReason stopReason = StopReason.END_TURN;
+
+			public Builder role(Role role) {
+				this.role = role;
+				return this;
+			}
+
+			public Builder content(Content content) {
+				this.content = content;
+				return this;
+			}
+
+			public Builder model(String model) {
+				this.model = model;
+				return this;
+			}
+
+			public Builder stopReason(StopReason stopReason) {
+				this.stopReason = stopReason;
+				return this;
+			}
+
+			public Builder message(String message) {
+				this.content = new TextContent(message);
+				return this;
+			}
+
+			public CreateMessageResult build() {
+				return new CreateMessageResult(role, content, model, stopReason);
+			}
+
+		}
+	}
 
 	// Elicitation
 	/**
-	 * Used by the server to send an elicitation to the client.
+	 * A request from the server to elicit additional information from the user via the
+	 * client.
 	 *
-	 * @param errorMessage The body of the elicitation message.
-	 * @param requestedSchema The elicitation response schema that must be satisfied.
+	 * @param message The message to present to the user
+	 * @param requestedSchema A restricted subset of JSON Schema. Only top-level
+	 * properties are allowed, without nesting
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ElicitRequest(// @formatter:off
-				@JsonProperty("message") String message,
-				@JsonProperty("requestedSchema") Map requestedSchema,
-				@JsonProperty("_meta") Map meta) implements Request {
-
-				// backwards compatibility constructor
-				public ElicitRequest(String message, Map requestedSchema) {
-						this(message, requestedSchema, null);
-				}
+	public record ElicitRequest( // @formatter:off
+		@JsonProperty("message") String message,
+		@JsonProperty("requestedSchema") Map requestedSchema,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		// backwards compatibility constructor
+		public ElicitRequest(String message, Map requestedSchema) {
+			this(message, requestedSchema, null);
+		}
+
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		public static class Builder {
+
+			private String message;
+
+			private Map requestedSchema;
+
+			private Map meta;
 
-				public static class Builder {
-						private String message;
-						private Map requestedSchema;
-						private Map meta;
-
-						public Builder message(String message) {
-								this.message = message;
-								return this;
-						}
-
-						public Builder requestedSchema(Map requestedSchema) {
-								this.requestedSchema = requestedSchema;
-								return this;
-						}
-
-						public Builder meta(Map meta) {
-								this.meta = meta;
-								return this;
-						}
-
-						public Builder progressToken(String progressToken) {
-								if (this.meta == null) {
-										this.meta = new HashMap<>();
-								}
-								this.meta.put("progressToken", progressToken);
-								return this;
-						}
-
-						public ElicitRequest build() {
-								return new ElicitRequest(message, requestedSchema, meta);
-						}
+			public Builder message(String message) {
+				this.message = message;
+				return this;
+			}
+
+			public Builder requestedSchema(Map requestedSchema) {
+				this.requestedSchema = requestedSchema;
+				return this;
+			}
+
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
+			public Builder progressToken(String progressToken) {
+				if (this.meta == null) {
+					this.meta = new HashMap<>();
 				}
-		}// @formatter:on
+				this.meta.put("progressToken", progressToken);
+				return this;
+			}
+
+			public ElicitRequest build() {
+				return new ElicitRequest(message, requestedSchema, meta);
+			}
 
+		}
+	}
+
+	/**
+	 * The client's response to an elicitation request.
+	 *
+	 * @param action The user action in response to the elicitation. "accept": User
+	 * submitted the form/confirmed the action, "decline": User explicitly declined the
+	 * action, "cancel": User dismissed without making an explicit choice
+	 * @param content The submitted form data, only present when action is "accept".
+	 * Contains values matching the requested schema
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ElicitResult(// @formatter:off
-				@JsonProperty("action") Action action,
-				@JsonProperty("content") Map content) {
-
-				public enum Action {
-						@JsonProperty("accept") ACCEPT,
-						@JsonProperty("decline") DECLINE,
-						@JsonProperty("cancel") CANCEL
-				}
+	public record ElicitResult( // @formatter:off
+		@JsonProperty("action") Action action,
+		@JsonProperty("content") Map content) { // @formatter:on
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		public enum Action {
 
-				public static class Builder {
-						private Action action;
-						private Map content;
+		// @formatter:off
+			@JsonProperty("accept") ACCEPT,
+			@JsonProperty("decline") DECLINE,
+			@JsonProperty("cancel") CANCEL
+		} // @formatter:on
 
-						public Builder message(Action action) {
-								this.action = action;
-								return this;
-						}
+		public static Builder builder() {
+			return new Builder();
+		}
 
-						public Builder content(Map content) {
-								this.content = content;
-								return this;
-						}
+		public static class Builder {
 
-						public ElicitResult build() {
-								return new ElicitResult(action, content);
-						}
-				}
-		}// @formatter:on
+			private Action action;
+
+			private Map content;
+
+			public Builder message(Action action) {
+				this.action = action;
+				return this;
+			}
+
+			public Builder content(Map content) {
+				this.content = content;
+				return this;
+			}
+
+			public ElicitResult build() {
+				return new ElicitResult(action, content);
+			}
+
+		}
+	}
 
 	// ---------------------------
 	// Pagination Interfaces
 	// ---------------------------
+	/**
+	 * A request that supports pagination using cursors.
+	 *
+	 * @param cursor An opaque token representing the current pagination position. If
+	 * provided, the server should return results starting after this cursor
+	 * @param meta See specification for notes on _meta usage
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record PaginatedRequest(// @formatter:off
-				@JsonProperty("cursor") String cursor,
-				@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
+	public record PaginatedRequest( // @formatter:off
+		@JsonProperty("cursor") String cursor,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
 		public PaginatedRequest(String cursor) {
 			this(cursor, null);
@@ -1678,6 +1932,13 @@ public PaginatedRequest() {
 		}
 	}
 
+	/**
+	 * An opaque token representing the pagination position after the last returned
+	 * result. If present, there may be more results available.
+	 *
+	 * @param nextCursor An opaque token representing the pagination position after the
+	 * last returned result. If present, there may be more results available
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record PaginatedResult(@JsonProperty("nextCursor") String nextCursor) {
@@ -1699,12 +1960,12 @@ public record PaginatedResult(@JsonProperty("nextCursor") String nextCursor) {
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ProgressNotification(// @formatter:off
-				@JsonProperty("progressToken") String progressToken,
-				@JsonProperty("progress") Double progress,
-				@JsonProperty("total") Double total,
-				@JsonProperty("message") String message) {
-		}// @formatter:on
+	public record ProgressNotification( // @formatter:off
+		@JsonProperty("progressToken") String progressToken,
+		@JsonProperty("progress") Double progress,
+		@JsonProperty("total") Double total,
+		@JsonProperty("message") String message) { // @formatter:on
+	}
 
 	/**
 	 * The Model Context Protocol (MCP) provides a standardized way for servers to send
@@ -1713,9 +1974,8 @@ public record ProgressNotification(// @formatter:off
 	 * @param uri The updated resource uri.
 	 */
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ResourcesUpdatedNotification(// @formatter:off
-		   @JsonProperty("uri") String uri) {
-		}// @formatter:on
+	public record ResourcesUpdatedNotification(@JsonProperty("uri") String uri) {
+	}
 
 	/**
 	 * The Model Context Protocol (MCP) provides a standardized way for servers to send
@@ -1728,63 +1988,77 @@ public record ResourcesUpdatedNotification(// @formatter:off
 	 * @param data JSON-serializable logging data.
 	 */
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record LoggingMessageNotification(// @formatter:off
-				@JsonProperty("level") LoggingLevel level,
-				@JsonProperty("logger") String logger,
-				@JsonProperty("data") String data) {
+	public record LoggingMessageNotification( // @formatter:off
+		@JsonProperty("level") LoggingLevel level,
+		@JsonProperty("logger") String logger,
+		@JsonProperty("data") String data) { // @formatter:on
 
-				public static Builder builder() {
-						return new Builder();
-				}
+		public static Builder builder() {
+			return new Builder();
+		}
 
-				public static class Builder {
-						private LoggingLevel level = LoggingLevel.INFO;
-						private String logger = "server";
-						private String data;
-
-						public Builder level(LoggingLevel level) {
-								this.level = level;
-								return this;
-						}
-
-						public Builder logger(String logger) {
-								this.logger = logger;
-								return this;
-						}
-
-						public Builder data(String data) {
-								this.data = data;
-								return this;
-						}
-
-						public LoggingMessageNotification build() {
-								return new LoggingMessageNotification(level, logger, data);
-						}
-				}
-		}// @formatter:on
-
-	public enum LoggingLevel {// @formatter:off
-				@JsonProperty("debug") DEBUG(0),
-				@JsonProperty("info") INFO(1),
-				@JsonProperty("notice") NOTICE(2),
-				@JsonProperty("warning") WARNING(3),
-				@JsonProperty("error") ERROR(4),
-				@JsonProperty("critical") CRITICAL(5),
-				@JsonProperty("alert") ALERT(6),
-				@JsonProperty("emergency") EMERGENCY(7);
-
-				private final int level;
-
-				LoggingLevel(int level) {
-						this.level = level;
-				}
+		public static class Builder {
 
-				public int level() {
-						return level;
-				}
+			private LoggingLevel level = LoggingLevel.INFO;
 
-		} // @formatter:on
+			private String logger = "server";
+
+			private String data;
+
+			public Builder level(LoggingLevel level) {
+				this.level = level;
+				return this;
+			}
+
+			public Builder logger(String logger) {
+				this.logger = logger;
+				return this;
+			}
+
+			public Builder data(String data) {
+				this.data = data;
+				return this;
+			}
+
+			public LoggingMessageNotification build() {
+				return new LoggingMessageNotification(level, logger, data);
+			}
+
+		}
+	}
+
+	public enum LoggingLevel {
+
+	// @formatter:off
+		@JsonProperty("debug") DEBUG(0),
+		@JsonProperty("info") INFO(1),
+		@JsonProperty("notice") NOTICE(2),
+		@JsonProperty("warning") WARNING(3),
+		@JsonProperty("error") ERROR(4),
+		@JsonProperty("critical") CRITICAL(5),
+		@JsonProperty("alert") ALERT(6),
+		@JsonProperty("emergency") EMERGENCY(7);
+		// @formatter:on
+
+		private final int level;
+
+		LoggingLevel(int level) {
+			this.level = level;
+		}
 
+		public int level() {
+			return level;
+		}
+
+	}
+
+	/**
+	 * A request from the client to the server, to enable or adjust logging.
+	 *
+	 * @param level The level of logging that the client wants to receive from the server.
+	 * The server should send all logs at this level and higher (i.e., more severe) to the
+	 * client as notifications/message
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record SetLevelRequest(@JsonProperty("level") LoggingLevel level) {
@@ -1801,12 +2075,19 @@ public sealed interface CompleteReference permits PromptReference, ResourceRefer
 
 	}
 
+	/**
+	 * Identifies a prompt for completion requests.
+	 *
+	 * @param type The reference type identifier (typically "ref/prompt")
+	 * @param name The name of the prompt
+	 * @param title An optional title for the prompt
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record PromptReference(// @formatter:off
-				@JsonProperty("type") String type,
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title ) implements McpSchema.CompleteReference, BaseMetadata { // @formatter:on
+	public record PromptReference( // @formatter:off
+		@JsonProperty("type") String type,
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title ) implements McpSchema.CompleteReference, BaseMetadata { // @formatter:on
 
 		public PromptReference(String type, String name) {
 			this(type, name, null);
@@ -1822,29 +2103,43 @@ public String identifier() {
 		}
 	}
 
+	/**
+	 * A reference to a resource or resource template definition for completion requests.
+	 *
+	 * @param type The reference type identifier (typically "ref/resource")
+	 * @param uri The URI or URI template of the resource
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ResourceReference(// @formatter:off
-				@JsonProperty("type") String type,
-				@JsonProperty("uri") String uri) implements McpSchema.CompleteReference {
+	public record ResourceReference( // @formatter:off
+		@JsonProperty("type") String type,
+		@JsonProperty("uri") String uri) implements McpSchema.CompleteReference { // @formatter:on
 
-				public ResourceReference(String uri) {
-						this("ref/resource", uri);
-				}
+		public ResourceReference(String uri) {
+			this("ref/resource", uri);
+		}
 
-				@Override
-				public String identifier() {
-						return uri();
-				}
-		}// @formatter:on
+		@Override
+		public String identifier() {
+			return uri();
+		}
+	}
 
+	/**
+	 * A request from the client to the server, to ask for completion options.
+	 *
+	 * @param ref A reference to a prompt or resource template definition
+	 * @param argument The argument's information for completion requests
+	 * @param meta See specification for notes on _meta usage
+	 * @param context Additional, optional context for completions
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record CompleteRequest(// @formatter:off
+	public record CompleteRequest( // @formatter:off
 		@JsonProperty("ref") McpSchema.CompleteReference ref,
 		@JsonProperty("argument") CompleteArgument argument,
 		@JsonProperty("_meta") Map meta,
-		@JsonProperty("context") CompleteContext context) implements Request {
+		@JsonProperty("context") CompleteContext context) implements Request { // @formatter:on
 
 		public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument, Map meta) {
 			this(ref, argument, meta, null);
@@ -1857,26 +2152,48 @@ public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argumen
 		public CompleteRequest(McpSchema.CompleteReference ref, CompleteArgument argument) {
 			this(ref, argument, null, null);
 		}
-		
-		public record CompleteArgument(
-			@JsonProperty("name") String name,
-			@JsonProperty("value") String value) {
+
+		/**
+		 * The argument's information for completion requests.
+		 *
+		 * @param name The name of the argument
+		 * @param value The value of the argument to use for completion matching
+		 */
+		public record CompleteArgument(@JsonProperty("name") String name, @JsonProperty("value") String value) {
 		}
 
-		public record CompleteContext(
-			@JsonProperty("arguments") Map arguments) {
-		}// @formatter:on
+		/**
+		 * Additional, optional context for completions.
+		 *
+		 * @param arguments Previously-resolved variables in a URI template or prompt
+		 */
+		public record CompleteContext(@JsonProperty("arguments") Map arguments) {
+		}
 	}
 
+	/**
+	 * The server's response to a completion/complete request.
+	 *
+	 * @param completion The completion information containing values and metadata
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record CompleteResult(@JsonProperty("completion") CompleteCompletion completion) { // @formatter:off
+	public record CompleteResult(@JsonProperty("completion") CompleteCompletion completion) {
 
-				public record CompleteCompletion(
-						@JsonProperty("values") List values,
-						@JsonProperty("total") Integer total,
-						@JsonProperty("hasMore") Boolean hasMore) {
-				}// @formatter:on
+		/**
+		 * The server's response to a completion/complete request
+		 *
+		 * @param values An array of completion values. Must not exceed 100 items
+		 * @param total The total number of completion options available. This can exceed
+		 * the number of values actually sent in the response
+		 * @param hasMore Indicates whether there are additional completion options beyond
+		 * those provided in the current response, even if the exact total is unknown
+		 */
+		public record CompleteCompletion( // @formatter:off
+				@JsonProperty("values") List values,
+				@JsonProperty("total") Integer total,
+				@JsonProperty("hasMore") Boolean hasMore) { // @formatter:on
+		}
 	}
 
 	// ---------------------------
@@ -1911,11 +2228,17 @@ else if (this instanceof ResourceLink) {
 
 	}
 
+	/**
+	 * Text provided to or from an LLM.
+	 *
+	 * @param annotations Optional annotations for the client
+	 * @param text The text content of the message
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record TextContent( // @formatter:off
-				@JsonProperty("annotations") Annotations annotations,
-				@JsonProperty("text") String text) implements Annotated, Content { // @formatter:on
+		@JsonProperty("annotations") Annotations annotations,
+		@JsonProperty("text") String text) implements Annotated, Content { // @formatter:on
 
 		public TextContent(String content) {
 			this(null, content);
@@ -1946,12 +2269,20 @@ public Double priority() {
 		}
 	}
 
+	/**
+	 * An image provided to or from an LLM.
+	 *
+	 * @param annotations Optional annotations for the client
+	 * @param data The base64-encoded image data
+	 * @param mimeType The MIME type of the image. Different providers may support
+	 * different image types
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ImageContent( // @formatter:off
-				@JsonProperty("annotations") Annotations annotations,
-				@JsonProperty("data") String data,
-				@JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on
+		@JsonProperty("annotations") Annotations annotations,
+		@JsonProperty("data") String data,
+		@JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -1978,19 +2309,36 @@ public Double priority() {
 		}
 	}
 
+	/**
+	 * Audio provided to or from an LLM.
+	 *
+	 * @param annotations Optional annotations for the client
+	 * @param data The base64-encoded audio data
+	 * @param mimeType The MIME type of the audio. Different providers may support
+	 * different audio types
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record AudioContent( // @formatter:off
-				@JsonProperty("annotations") Annotations annotations,
-				@JsonProperty("data") String data,
-				@JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on
+		@JsonProperty("annotations") Annotations annotations,
+		@JsonProperty("data") String data,
+		@JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on
 	}
 
+	/**
+	 * The contents of a resource, embedded into a prompt or tool call result.
+	 *
+	 * It is up to the client how best to render embedded resources for the benefit of the
+	 * LLM and/or the user.
+	 *
+	 * @param annotations Optional annotations for the client
+	 * @param resource The resource contents that are embedded
+	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record EmbeddedResource( // @formatter:off
-				@JsonProperty("annotations") Annotations annotations,
-				@JsonProperty("resource") ResourceContents resource) implements Annotated, Content { // @formatter:on
+		@JsonProperty("annotations") Annotations annotations,
+		@JsonProperty("resource") ResourceContents resource) implements Annotated, Content { // @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -2038,13 +2386,13 @@ public Double priority() {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ResourceLink( // @formatter:off
-				@JsonProperty("name") String name,
-				@JsonProperty("title") String title,
-				@JsonProperty("uri") String uri,
-				@JsonProperty("description") String description,
-				@JsonProperty("mimeType") String mimeType,
-				@JsonProperty("size") Long size,
-				@JsonProperty("annotations") Annotations annotations) implements Annotated, Content, ResourceContent { // @formatter:on
+		@JsonProperty("name") String name,
+		@JsonProperty("title") String title,
+		@JsonProperty("uri") String uri,
+		@JsonProperty("description") String description,
+		@JsonProperty("mimeType") String mimeType,
+		@JsonProperty("size") Long size,
+		@JsonProperty("annotations") Annotations annotations) implements Annotated, Content, ResourceContent { // @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -2138,9 +2486,9 @@ public ResourceLink build() {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record Root( // @formatter:off
-				@JsonProperty("uri") String uri,
-				@JsonProperty("name") String name) {
-		} // @formatter:on
+		@JsonProperty("uri") String uri,
+		@JsonProperty("name") String name) { // @formatter:on
+	}
 
 	/**
 	 * The client's response to a roots/list request from the server. This result contains
@@ -2156,12 +2504,12 @@ public record Root( // @formatter:off
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListRootsResult( // @formatter:off
-				@JsonProperty("roots") List roots,
-				@JsonProperty("nextCursor") String nextCursor) {
+		@JsonProperty("roots") List roots,
+		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
 
-				public ListRootsResult(List roots) {
-						this(roots, null);
-				}
-		} // @formatter:on
+		public ListRootsResult(List roots) {
+			this(roots, null);
+		}
+	}
 
 }

From 87cdaf883a62077944eeae5be8ae4426cd954cf3 Mon Sep 17 00:00:00 2001
From: Anurag Pant 
Date: Tue, 1 Jul 2025 11:27:07 -0700
Subject: [PATCH 013/125] feat: Add _meta support to MCPSchema (#368)

- Add _meta field to all MCP schema records for extensible metadata support
- Introduce Result and Notification sealed interfaces for better type organization
- Update Request interface to include SubscribeRequest and UnsubscribeRequest
- Add backwards-compatible constructors for existing record types
- Enhance test coverage for metadata field functionality

Breaking change: Modifyibng the Request seald inteface is a breaking change.
---
 .../modelcontextprotocol/spec/McpSchema.java  | 401 +++++++++++++++---
 .../spec/McpSchemaTests.java                  | 102 +++--
 2 files changed, 424 insertions(+), 79 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 4a570aea0..75deb5a0f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -35,6 +35,7 @@
  * @author Christian Tzolov
  * @author Luca Chang
  * @author Surbhi Bansal
+ * @author Anurag Pant
  */
 public final class McpSchema {
 
@@ -144,8 +145,9 @@ public static final class ErrorCodes {
 
 	}
 
-	public sealed interface Request permits InitializeRequest, CallToolRequest, CreateMessageRequest, ElicitRequest,
-			CompleteRequest, GetPromptRequest, PaginatedRequest, ReadResourceRequest {
+	public sealed interface Request
+			permits InitializeRequest, CallToolRequest, CreateMessageRequest, ElicitRequest, CompleteRequest,
+			GetPromptRequest, ReadResourceRequest, SubscribeRequest, UnsubscribeRequest, PaginatedRequest {
 
 		Map meta();
 
@@ -158,6 +160,21 @@ default String progressToken() {
 
 	}
 
+	public sealed interface Result permits InitializeResult, ListResourcesResult, ListResourceTemplatesResult,
+			ReadResourceResult, ListPromptsResult, GetPromptResult, ListToolsResult, CallToolResult,
+			CreateMessageResult, ElicitResult, CompleteResult, ListRootsResult {
+
+		Map meta();
+
+	}
+
+	public sealed interface Notification
+			permits ProgressNotification, LoggingMessageNotification, ResourcesUpdatedNotification {
+
+		Map meta();
+
+	}
+
 	private static final TypeReference> MAP_TYPE_REF = new TypeReference<>() {
 	};
 
@@ -211,7 +228,6 @@ public sealed interface JSONRPCMessage permits JSONRPCRequest, JSONRPCNotificati
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	// TODO: batching support
 	// @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
 	public record JSONRPCRequest( // @formatter:off
 		@JsonProperty("jsonrpc") String jsonrpc,
@@ -312,6 +328,7 @@ public InitializeRequest(String protocolVersion, ClientCapabilities capabilities
 	 * This can be used by clients to improve the LLM's understanding of available tools,
 	 * resources, etc. It can be thought of like a "hint" to the model. For example, this
 	 * information MAY be added to the system prompt
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -319,7 +336,13 @@ public record InitializeResult( // @formatter:off
 		@JsonProperty("protocolVersion") String protocolVersion,
 		@JsonProperty("capabilities") ServerCapabilities capabilities,
 		@JsonProperty("serverInfo") Implementation serverInfo,
-		@JsonProperty("instructions") String instructions) { // @formatter:on
+		@JsonProperty("instructions") String instructions,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
+
+		public InitializeResult(String protocolVersion, ServerCapabilities capabilities, Implementation serverInfo,
+				String instructions) {
+			this(protocolVersion, capabilities, serverInfo, instructions, null);
+		}
 	}
 
 	/**
@@ -660,6 +683,7 @@ public interface BaseMetadata {
 	 * sizes and estimate context window usage.
 	 * @param annotations Optional annotations for the client. The client can use
 	 * annotations to inform how objects are used or displayed.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -670,7 +694,18 @@ public record Resource( // @formatter:off
 		@JsonProperty("description") String description,
 		@JsonProperty("mimeType") String mimeType,
 		@JsonProperty("size") Long size,
-		@JsonProperty("annotations") Annotations annotations) implements Annotated, ResourceContent { // @formatter:on
+		@JsonProperty("annotations") Annotations annotations,
+		@JsonProperty("_meta") Map meta) implements Annotated, ResourceContent { // @formatter:on
+
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link Resource#builder()} instead.
+		 */
+		@Deprecated
+		public Resource(String uri, String name, String title, String description, String mimeType, Long size,
+				Annotations annotations) {
+			this(uri, name, title, description, mimeType, size, annotations, null);
+		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -679,7 +714,7 @@ public record Resource( // @formatter:off
 		@Deprecated
 		public Resource(String uri, String name, String description, String mimeType, Long size,
 				Annotations annotations) {
-			this(uri, name, null, description, mimeType, null, annotations);
+			this(uri, name, null, description, mimeType, size, annotations, null);
 		}
 
 		/**
@@ -688,7 +723,7 @@ public Resource(String uri, String name, String description, String mimeType, Lo
 		 */
 		@Deprecated
 		public Resource(String uri, String name, String description, String mimeType, Annotations annotations) {
-			this(uri, name, null, description, mimeType, null, annotations);
+			this(uri, name, null, description, mimeType, null, annotations, null);
 		}
 
 		public static Builder builder() {
@@ -711,6 +746,8 @@ public static class Builder {
 
 			private Annotations annotations;
 
+			private Map meta;
+
 			public Builder uri(String uri) {
 				this.uri = uri;
 				return this;
@@ -746,11 +783,16 @@ public Builder annotations(Annotations annotations) {
 				return this;
 			}
 
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
 			public Resource build() {
 				Assert.hasText(uri, "uri must not be empty");
 				Assert.hasText(name, "name must not be empty");
 
-				return new Resource(uri, name, title, description, mimeType, size, annotations);
+				return new Resource(uri, name, title, description, mimeType, size, annotations, meta);
 			}
 
 		}
@@ -758,7 +800,6 @@ public Resource build() {
 
 	/**
 	 * Resource templates allow servers to expose parameterized resources using URI
-	 * templates.
 	 *
 	 * @param uriTemplate A URI template that can be used to generate URIs for this
 	 * resource.
@@ -772,6 +813,8 @@ public Resource build() {
 	 * @param annotations Optional annotations for the client. The client can use
 	 * annotations to inform how objects are used or displayed.
 	 * @see RFC 6570
+	 * @param meta See specification for notes on _meta usage
+	 *
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -781,7 +824,13 @@ public record ResourceTemplate( // @formatter:off
 		@JsonProperty("title") String title,
 		@JsonProperty("description") String description,
 		@JsonProperty("mimeType") String mimeType,
-		@JsonProperty("annotations") Annotations annotations) implements Annotated, BaseMetadata { // @formatter:on
+		@JsonProperty("annotations") Annotations annotations,
+		@JsonProperty("_meta") Map meta) implements Annotated, BaseMetadata { // @formatter:on
+
+		public ResourceTemplate(String uriTemplate, String name, String title, String description, String mimeType,
+				Annotations annotations) {
+			this(uriTemplate, name, title, description, mimeType, annotations, null);
+		}
 
 		public ResourceTemplate(String uriTemplate, String name, String description, String mimeType,
 				Annotations annotations) {
@@ -795,12 +844,18 @@ public ResourceTemplate(String uriTemplate, String name, String description, Str
 	 * @param resources A list of resources that the server provides
 	 * @param nextCursor An opaque token representing the pagination position after the
 	 * last returned result. If present, there may be more results available
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListResourcesResult( // @formatter:off
 		@JsonProperty("resources") List resources,
-		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+		@JsonProperty("nextCursor") String nextCursor,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
+
+		public ListResourcesResult(List resources, String nextCursor) {
+			this(resources, nextCursor, null);
+		}
 	}
 
 	/**
@@ -809,12 +864,18 @@ public record ListResourcesResult( // @formatter:off
 	 * @param resourceTemplates A list of resource templates that the server provides
 	 * @param nextCursor An opaque token representing the pagination position after the
 	 * last returned result. If present, there may be more results available
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListResourceTemplatesResult( // @formatter:off
 		@JsonProperty("resourceTemplates") List resourceTemplates,
-		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+		@JsonProperty("nextCursor") String nextCursor,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
+
+		public ListResourceTemplatesResult(List resourceTemplates, String nextCursor) {
+			this(resourceTemplates, nextCursor, null);
+		}
 	}
 
 	/**
@@ -839,10 +900,17 @@ public ReadResourceRequest(String uri) {
 	 * The server's response to a resources/read request from the client.
 	 *
 	 * @param contents The contents of the resource
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ReadResourceResult(@JsonProperty("contents") List contents) {
+	public record ReadResourceResult( // @formatter:off
+		@JsonProperty("contents") List contents,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
+
+		public ReadResourceResult(List contents) {
+			this(contents, null);
+		}
 	}
 
 	/**
@@ -851,10 +919,17 @@ public record ReadResourceResult(@JsonProperty("contents") List meta) implements Request { // @formatter:on
+
+		public SubscribeRequest(String uri) {
+			this(uri, null);
+		}
 	}
 
 	/**
@@ -862,10 +937,17 @@ public record SubscribeRequest(@JsonProperty("uri") String uri) {
 	 * from the server. This should follow a previous resources/subscribe request.
 	 *
 	 * @param uri The URI of the resource to unsubscribe from
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record UnsubscribeRequest(@JsonProperty("uri") String uri) {
+	public record UnsubscribeRequest( // @formatter:off
+		@JsonProperty("uri") String uri,
+		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
+
+		public UnsubscribeRequest(String uri) {
+			this(uri, null);
+		}
 	}
 
 	/**
@@ -888,6 +970,14 @@ public sealed interface ResourceContents permits TextResourceContents, BlobResou
 		 */
 		String mimeType();
 
+		/**
+		 * @see Specification
+		 * for notes on _meta usage
+		 * @return additional metadata related to this resource.
+		 */
+		Map meta();
+
 	}
 
 	/**
@@ -897,13 +987,19 @@ public sealed interface ResourceContents permits TextResourceContents, BlobResou
 	 * @param mimeType the MIME type of this resource.
 	 * @param text the text of the resource. This must only be set if the resource can
 	 * actually be represented as text (not binary data).
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record TextResourceContents( // @formatter:off
 		@JsonProperty("uri") String uri,
 		@JsonProperty("mimeType") String mimeType,
-		@JsonProperty("text") String text) implements ResourceContents { // @formatter:on
+		@JsonProperty("text") String text,
+		@JsonProperty("_meta") Map meta) implements ResourceContents { // @formatter:on
+
+		public TextResourceContents(String uri, String mimeType, String text) {
+			this(uri, mimeType, text, null);
+		}
 	}
 
 	/**
@@ -914,13 +1010,19 @@ public record TextResourceContents( // @formatter:off
 	 * @param blob a base64-encoded string representing the binary data of the resource.
 	 * This must only be set if the resource can actually be represented as binary data
 	 * (not text).
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record BlobResourceContents( // @formatter:off
 		@JsonProperty("uri") String uri,
 		@JsonProperty("mimeType") String mimeType,
-		@JsonProperty("blob") String blob) implements ResourceContents { // @formatter:on
+		@JsonProperty("blob") String blob,
+		@JsonProperty("_meta") Map meta) implements ResourceContents { // @formatter:on
+
+		public BlobResourceContents(String uri, String mimeType, String blob) {
+			this(uri, mimeType, blob, null);
+		}
 	}
 
 	// ---------------------------
@@ -933,6 +1035,7 @@ public record BlobResourceContents( // @formatter:off
 	 * @param title An optional title for the prompt.
 	 * @param description An optional description of what this prompt provides.
 	 * @param arguments A list of arguments to use for templating the prompt.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -940,11 +1043,16 @@ public record Prompt( // @formatter:off
 		@JsonProperty("name") String name,
 		@JsonProperty("title") String title,
 		@JsonProperty("description") String description,
-		@JsonProperty("arguments") List arguments) implements BaseMetadata { // @formatter:on
+		@JsonProperty("arguments") List arguments,
+		@JsonProperty("_meta") Map meta) implements BaseMetadata { // @formatter:on
 
 		public Prompt(String name, String description, List arguments) {
 			this(name, null, description, arguments != null ? arguments : new ArrayList<>());
 		}
+
+		public Prompt(String name, String title, String description, List arguments) {
+			this(name, title, description, arguments != null ? arguments : new ArrayList<>(), null);
+		}
 	}
 
 	/**
@@ -990,12 +1098,18 @@ public record PromptMessage( // @formatter:off
 	 * @param prompts A list of prompts that the server provides.
 	 * @param nextCursor An optional cursor for pagination. If present, indicates there
 	 * are more prompts available.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListPromptsResult( // @formatter:off
 		@JsonProperty("prompts") List prompts,
-		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+		@JsonProperty("nextCursor") String nextCursor,
+		@JsonProperty("_meta") Map meta) implements Result  { // @formatter:on
+
+		public ListPromptsResult(List prompts, String nextCursor) {
+			this(prompts, nextCursor, null);
+		}
 	}
 
 	/**
@@ -1003,6 +1117,7 @@ public record ListPromptsResult( // @formatter:off
 	 *
 	 * @param name The name of the prompt or prompt template.
 	 * @param arguments Arguments to use for templating the prompt.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -1021,12 +1136,18 @@ public GetPromptRequest(String name, Map arguments) {
 	 *
 	 * @param description An optional description for the prompt.
 	 * @param messages A list of messages to display as part of the prompt.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record GetPromptResult( // @formatter:off
 		@JsonProperty("description") String description,
-		@JsonProperty("messages") List messages) { // @formatter:on
+		@JsonProperty("messages") List messages,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
+
+		public GetPromptResult(String description, List messages) {
+			this(description, messages, null);
+		}
 	}
 
 	// ---------------------------
@@ -1038,12 +1159,18 @@ public record GetPromptResult( // @formatter:off
 	 * @param tools A list of tools that the server provides.
 	 * @param nextCursor An optional cursor for pagination. If present, indicates there
 	 * are more tools available.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListToolsResult( // @formatter:off
 		@JsonProperty("tools") List tools,
-		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+		@JsonProperty("nextCursor") String nextCursor,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
+
+		public ListToolsResult(List tools, String nextCursor) {
+			this(tools, nextCursor, null);
+		}
 	}
 
 	/**
@@ -1103,6 +1230,7 @@ public record ToolAnnotations( // @formatter:off
 	 * @param outputSchema An optional JSON Schema object defining the structure of the
 	 * tool's output returned in the structuredContent field of a CallToolResult.
 	 * @param annotations Optional additional tool information.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -1112,7 +1240,8 @@ public record Tool( // @formatter:off
 		@JsonProperty("description") String description,
 		@JsonProperty("inputSchema") JsonSchema inputSchema,
 		@JsonProperty("outputSchema") Map outputSchema,
-		@JsonProperty("annotations") ToolAnnotations annotations) { // @formatter:on
+		@JsonProperty("annotations") ToolAnnotations annotations,
+		@JsonProperty("_meta") Map meta) { // @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -1120,7 +1249,7 @@ public record Tool( // @formatter:off
 		 */
 		@Deprecated
 		public Tool(String name, String description, JsonSchema inputSchema, ToolAnnotations annotations) {
-			this(name, null, description, inputSchema, null, annotations);
+			this(name, null, description, inputSchema, null, annotations, null);
 		}
 
 		/**
@@ -1129,7 +1258,7 @@ public Tool(String name, String description, JsonSchema inputSchema, ToolAnnotat
 		 */
 		@Deprecated
 		public Tool(String name, String description, String inputSchema) {
-			this(name, null, description, parseSchema(inputSchema), null, null);
+			this(name, null, description, parseSchema(inputSchema), null, null, null);
 		}
 
 		/**
@@ -1138,7 +1267,7 @@ public Tool(String name, String description, String inputSchema) {
 		 */
 		@Deprecated
 		public Tool(String name, String description, String schema, ToolAnnotations annotations) {
-			this(name, null, description, parseSchema(schema), null, annotations);
+			this(name, null, description, parseSchema(schema), null, annotations, null);
 		}
 
 		/**
@@ -1148,7 +1277,17 @@ public Tool(String name, String description, String schema, ToolAnnotations anno
 		@Deprecated
 		public Tool(String name, String description, String inputSchema, String outputSchema,
 				ToolAnnotations annotations) {
-			this(name, null, description, parseSchema(inputSchema), schemaToMap(outputSchema), annotations);
+			this(name, null, description, parseSchema(inputSchema), schemaToMap(outputSchema), annotations, null);
+		}
+
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link Tool#builder()} instead.
+		 */
+		@Deprecated
+		public Tool(String name, String title, String description, String inputSchema, String outputSchema,
+				ToolAnnotations annotations) {
+			this(name, title, description, parseSchema(inputSchema), schemaToMap(outputSchema), annotations, null);
 		}
 
 		public static Builder builder() {
@@ -1169,6 +1308,8 @@ public static class Builder {
 
 			private ToolAnnotations annotations;
 
+			private Map meta;
+
 			public Builder name(String name) {
 				this.name = name;
 				return this;
@@ -1209,9 +1350,14 @@ public Builder annotations(ToolAnnotations annotations) {
 				return this;
 			}
 
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
 			public Tool build() {
 				Assert.hasText(name, "name must not be empty");
-				return new Tool(name, title, description, inputSchema, outputSchema, annotations);
+				return new Tool(name, title, description, inputSchema, outputSchema, annotations, meta);
 			}
 
 		}
@@ -1242,6 +1388,7 @@ private static JsonSchema parseSchema(String schema) {
 	 * tools/list.
 	 * @param arguments Arguments to pass to the tool. These must conform to the tool's
 	 * input schema.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -1324,17 +1471,24 @@ public CallToolRequest build() {
 	 * contains error information. If false or absent, indicates successful execution.
 	 * @param structuredContent An optional JSON object that represents the structured
 	 * result of the tool call.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record CallToolResult( // @formatter:off
 		@JsonProperty("content") List content,
 		@JsonProperty("isError") Boolean isError,
-		@JsonProperty("structuredContent") Map structuredContent) { // @formatter:on
+		@JsonProperty("structuredContent") Map structuredContent,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
 
 		// backwards compatibility constructor
 		public CallToolResult(List content, Boolean isError) {
-			this(content, isError, null);
+			this(content, isError, null, null);
+		}
+
+		// backwards compatibility constructor
+		public CallToolResult(List content, Boolean isError, Map structuredContent) {
+			this(content, isError, structuredContent, null);
 		}
 
 		/**
@@ -1347,7 +1501,7 @@ public CallToolResult(List content, Boolean isError) {
 		 * execution.
 		 */
 		public CallToolResult(String content, Boolean isError) {
-			this(List.of(new TextContent(content)), isError);
+			this(List.of(new TextContent(content)), isError, null);
 		}
 
 		/**
@@ -1369,6 +1523,8 @@ public static class Builder {
 
 			private Map structuredContent;
 
+			private Map meta;
+
 			/**
 			 * Sets the content list for the tool result.
 			 * @param content the content list
@@ -1443,12 +1599,22 @@ public Builder isError(Boolean isError) {
 				return this;
 			}
 
+			/**
+			 * Sets the metadata for the tool result.
+			 * @param meta metadata
+			 * @return this builder
+			 */
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
 			/**
 			 * Builds a new {@link CallToolResult} instance.
 			 * @return a new CallToolResult instance
 			 */
 			public CallToolResult build() {
-				return new CallToolResult(content, isError, structuredContent);
+				return new CallToolResult(content, isError, structuredContent, meta);
 			}
 
 		}
@@ -1710,6 +1876,7 @@ public CreateMessageRequest build() {
 	 * @param content The content of the sampled message
 	 * @param model The name of the model that generated the message
 	 * @param stopReason The reason why sampling stopped, if known
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -1717,7 +1884,8 @@ public record CreateMessageResult( // @formatter:off
 		@JsonProperty("role") Role role,
 		@JsonProperty("content") Content content,
 		@JsonProperty("model") String model,
-		@JsonProperty("stopReason") StopReason stopReason) { // @formatter:on
+		@JsonProperty("stopReason") StopReason stopReason,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
 
 		public enum StopReason {
 
@@ -1744,6 +1912,10 @@ private static StopReason of(String value) {
 
 		}
 
+		public CreateMessageResult(Role role, Content content, String model, StopReason stopReason) {
+			this(role, content, model, stopReason, null);
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}
@@ -1758,6 +1930,8 @@ public static class Builder {
 
 			private StopReason stopReason = StopReason.END_TURN;
 
+			private Map meta;
+
 			public Builder role(Role role) {
 				this.role = role;
 				return this;
@@ -1783,8 +1957,13 @@ public Builder message(String message) {
 				return this;
 			}
 
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
 			public CreateMessageResult build() {
-				return new CreateMessageResult(role, content, model, stopReason);
+				return new CreateMessageResult(role, content, model, stopReason, meta);
 			}
 
 		}
@@ -1862,12 +2041,14 @@ public ElicitRequest build() {
 	 * action, "cancel": User dismissed without making an explicit choice
 	 * @param content The submitted form data, only present when action is "accept".
 	 * Contains values matching the requested schema
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ElicitResult( // @formatter:off
 		@JsonProperty("action") Action action,
-		@JsonProperty("content") Map content) { // @formatter:on
+		@JsonProperty("content") Map content,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
 
 		public enum Action {
 
@@ -1877,6 +2058,11 @@ public enum Action {
 			@JsonProperty("cancel") CANCEL
 		} // @formatter:on
 
+		// backwards compatibility constructor
+		public ElicitResult(Action action, Map content) {
+			this(action, content, null);
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}
@@ -1887,6 +2073,8 @@ public static class Builder {
 
 			private Map content;
 
+			private Map meta;
+
 			public Builder message(Action action) {
 				this.action = action;
 				return this;
@@ -1897,8 +2085,13 @@ public Builder content(Map content) {
 				return this;
 			}
 
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
 			public ElicitResult build() {
-				return new ElicitResult(action, content);
+				return new ElicitResult(action, content, meta);
 			}
 
 		}
@@ -1957,6 +2150,7 @@ public record PaginatedResult(@JsonProperty("nextCursor") String nextCursor) {
 	 * @param progress A value indicating the current progress.
 	 * @param total An optional total amount of work to be done, if known.
 	 * @param message An optional message providing additional context about the progress.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -1964,7 +2158,12 @@ public record ProgressNotification( // @formatter:off
 		@JsonProperty("progressToken") String progressToken,
 		@JsonProperty("progress") Double progress,
 		@JsonProperty("total") Double total,
-		@JsonProperty("message") String message) { // @formatter:on
+		@JsonProperty("message") String message,
+		@JsonProperty("_meta") Map meta) implements Notification { // @formatter:on
+
+		public ProgressNotification(String progressToken, double progress, Double total, String message) {
+			this(progressToken, progress, total, message, null);
+		}
 	}
 
 	/**
@@ -1972,9 +2171,16 @@ public record ProgressNotification( // @formatter:off
 	 * resources update message to clients.
 	 *
 	 * @param uri The updated resource uri.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record ResourcesUpdatedNotification(@JsonProperty("uri") String uri) {
+	public record ResourcesUpdatedNotification(// @formatter:off
+		@JsonProperty("uri") String uri,
+		@JsonProperty("_meta") Map meta) implements Notification { // @formatter:on
+
+		public ResourcesUpdatedNotification(String uri) {
+			this(uri, null);
+		}
 	}
 
 	/**
@@ -1986,12 +2192,19 @@ public record ResourcesUpdatedNotification(@JsonProperty("uri") String uri) {
 	 * @param level The severity levels. The minimum log level is set by the client.
 	 * @param logger The logger that generated the message.
 	 * @param data JSON-serializable logging data.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record LoggingMessageNotification( // @formatter:off
 		@JsonProperty("level") LoggingLevel level,
 		@JsonProperty("logger") String logger,
-		@JsonProperty("data") String data) { // @formatter:on
+		@JsonProperty("data") String data,
+		@JsonProperty("_meta") Map meta) implements Notification { // @formatter:on
+
+		// backwards compatibility constructor
+		public LoggingMessageNotification(LoggingLevel level, String logger, String data) {
+			this(level, logger, data, null);
+		}
 
 		public static Builder builder() {
 			return new Builder();
@@ -2005,6 +2218,8 @@ public static class Builder {
 
 			private String data;
 
+			private Map meta;
+
 			public Builder level(LoggingLevel level) {
 				this.level = level;
 				return this;
@@ -2020,8 +2235,13 @@ public Builder data(String data) {
 				return this;
 			}
 
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
 			public LoggingMessageNotification build() {
-				return new LoggingMessageNotification(level, logger, data);
+				return new LoggingMessageNotification(level, logger, data, meta);
 			}
 
 		}
@@ -2175,10 +2395,17 @@ public record CompleteContext(@JsonProperty("arguments") Map arg
 	 * The server's response to a completion/complete request.
 	 *
 	 * @param completion The completion information containing values and metadata
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record CompleteResult(@JsonProperty("completion") CompleteCompletion completion) {
+	public record CompleteResult(@JsonProperty("completion") CompleteCompletion completion,
+			@JsonProperty("_meta") Map meta) implements Result {
+
+		// backwards compatibility constructor
+		public CompleteResult(CompleteCompletion completion) {
+			this(completion, null);
+		}
 
 		/**
 		 * The server's response to a completion/complete request
@@ -2207,6 +2434,8 @@ public record CompleteCompletion( // @formatter:off
 			@JsonSubTypes.Type(value = ResourceLink.class, name = "resource_link") })
 	public sealed interface Content permits TextContent, ImageContent, AudioContent, EmbeddedResource, ResourceLink {
 
+		Map meta();
+
 		default String type() {
 			if (this instanceof TextContent) {
 				return "text";
@@ -2233,29 +2462,37 @@ else if (this instanceof ResourceLink) {
 	 *
 	 * @param annotations Optional annotations for the client
 	 * @param text The text content of the message
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record TextContent( // @formatter:off
 		@JsonProperty("annotations") Annotations annotations,
-		@JsonProperty("text") String text) implements Annotated, Content { // @formatter:on
+		@JsonProperty("text") String text,
+		@JsonProperty("_meta") Map meta) implements Annotated, Content { // @formatter:on
+
+		public TextContent(Annotations annotations, String text) {
+			this(annotations, text, null);
+		}
 
 		public TextContent(String content) {
-			this(null, content);
+			this(null, content, null);
 		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link TextContent#TextContent(Annotations, String)} instead.
 		 */
+		@Deprecated
 		public TextContent(List audience, Double priority, String content) {
-			this(audience != null || priority != null ? new Annotations(audience, priority) : null, content);
+			this(audience != null || priority != null ? new Annotations(audience, priority) : null, content, null);
 		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link TextContent#annotations()} instead.
 		 */
+		@Deprecated
 		public List audience() {
 			return annotations == null ? null : annotations.audience();
 		}
@@ -2264,6 +2501,7 @@ public List audience() {
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link TextContent#annotations()} instead.
 		 */
+		@Deprecated
 		public Double priority() {
 			return annotations == null ? null : annotations.priority();
 		}
@@ -2276,26 +2514,35 @@ public Double priority() {
 	 * @param data The base64-encoded image data
 	 * @param mimeType The MIME type of the image. Different providers may support
 	 * different image types
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ImageContent( // @formatter:off
 		@JsonProperty("annotations") Annotations annotations,
 		@JsonProperty("data") String data,
-		@JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on
+		@JsonProperty("mimeType") String mimeType,
+		@JsonProperty("_meta") Map meta) implements Annotated, Content { // @formatter:on
+
+		public ImageContent(Annotations annotations, String data, String mimeType) {
+			this(annotations, data, mimeType, null);
+		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link ImageContent#ImageContent(Annotations, String, String)} instead.
 		 */
+		@Deprecated
 		public ImageContent(List audience, Double priority, String data, String mimeType) {
-			this(audience != null || priority != null ? new Annotations(audience, priority) : null, data, mimeType);
+			this(audience != null || priority != null ? new Annotations(audience, priority) : null, data, mimeType,
+					null);
 		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link ImageContent#annotations()} instead.
 		 */
+		@Deprecated
 		public List audience() {
 			return annotations == null ? null : annotations.audience();
 		}
@@ -2304,6 +2551,7 @@ public List audience() {
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link ImageContent#annotations()} instead.
 		 */
+		@Deprecated
 		public Double priority() {
 			return annotations == null ? null : annotations.priority();
 		}
@@ -2316,13 +2564,20 @@ public Double priority() {
 	 * @param data The base64-encoded audio data
 	 * @param mimeType The MIME type of the audio. Different providers may support
 	 * different audio types
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record AudioContent( // @formatter:off
 		@JsonProperty("annotations") Annotations annotations,
 		@JsonProperty("data") String data,
-		@JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on
+		@JsonProperty("mimeType") String mimeType,
+		@JsonProperty("_meta") Map meta) implements Annotated, Content { // @formatter:on
+
+		// backwards compatibility constructor
+		public AudioContent(Annotations annotations, String data, String mimeType) {
+			this(annotations, data, mimeType, null);
+		}
 	}
 
 	/**
@@ -2333,26 +2588,35 @@ public record AudioContent( // @formatter:off
 	 *
 	 * @param annotations Optional annotations for the client
 	 * @param resource The resource contents that are embedded
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record EmbeddedResource( // @formatter:off
 		@JsonProperty("annotations") Annotations annotations,
-		@JsonProperty("resource") ResourceContents resource) implements Annotated, Content { // @formatter:on
+		@JsonProperty("resource") ResourceContents resource,
+		@JsonProperty("_meta") Map meta) implements Annotated, Content { // @formatter:on
+
+		// backwards compatibility constructor
+		public EmbeddedResource(Annotations annotations, ResourceContents resource) {
+			this(annotations, resource, null);
+		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link EmbeddedResource#EmbeddedResource(Annotations, ResourceContents)}
 		 * instead.
 		 */
+		@Deprecated
 		public EmbeddedResource(List audience, Double priority, ResourceContents resource) {
-			this(audience != null || priority != null ? new Annotations(audience, priority) : null, resource);
+			this(audience != null || priority != null ? new Annotations(audience, priority) : null, resource, null);
 		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link EmbeddedResource#annotations()} instead.
 		 */
+		@Deprecated
 		public List audience() {
 			return annotations == null ? null : annotations.audience();
 		}
@@ -2361,6 +2625,7 @@ public List audience() {
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
 		 * {@link EmbeddedResource#annotations()} instead.
 		 */
+		@Deprecated
 		public Double priority() {
 			return annotations == null ? null : annotations.priority();
 		}
@@ -2382,6 +2647,7 @@ public Double priority() {
 	 * sizes and estimate context window usage.
 	 * @param annotations Optional annotations for the client. The client can use
 	 * annotations to inform how objects are used or displayed.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
@@ -2392,7 +2658,19 @@ public record ResourceLink( // @formatter:off
 		@JsonProperty("description") String description,
 		@JsonProperty("mimeType") String mimeType,
 		@JsonProperty("size") Long size,
-		@JsonProperty("annotations") Annotations annotations) implements Annotated, Content, ResourceContent { // @formatter:on
+		@JsonProperty("annotations") Annotations annotations,
+		@JsonProperty("_meta") Map meta) implements Annotated, Content, ResourceContent { // @formatter:on
+
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes. Use
+		 * {@link ResourceLink#ResourceLink(String, String, String, String, String, Long, Annotations)}
+		 * instead.
+		 */
+		@Deprecated
+		public ResourceLink(String name, String title, String uri, String description, String mimeType, Long size,
+				Annotations annotations) {
+			this(name, title, uri, description, mimeType, size, annotations, null);
+		}
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -2425,6 +2703,8 @@ public static class Builder {
 
 			private Long size;
 
+			private Map meta;
+
 			public Builder name(String name) {
 				this.name = name;
 				return this;
@@ -2460,11 +2740,16 @@ public Builder size(Long size) {
 				return this;
 			}
 
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
 			public ResourceLink build() {
 				Assert.hasText(uri, "uri must not be empty");
 				Assert.hasText(name, "name must not be empty");
 
-				return new ResourceLink(name, title, uri, description, mimeType, size, annotations);
+				return new ResourceLink(name, title, uri, description, mimeType, size, annotations, meta);
 			}
 
 		}
@@ -2482,12 +2767,18 @@ public ResourceLink build() {
 	 * @param name An optional name for the root. This can be used to provide a
 	 * human-readable identifier for the root, which may be useful for display purposes or
 	 * for referencing the root in other parts of the application.
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record Root( // @formatter:off
 		@JsonProperty("uri") String uri,
-		@JsonProperty("name") String name) { // @formatter:on
+		@JsonProperty("name") String name,
+		@JsonProperty("_meta") Map meta) { // @formatter:on
+
+		public Root(String uri, String name) {
+			this(uri, name, null);
+		}
 	}
 
 	/**
@@ -2500,16 +2791,22 @@ public record Root( // @formatter:off
 	 * @param nextCursor An optional cursor for pagination. If present, indicates there
 	 * are more roots available. The client can use this cursor to request the next page
 	 * of results by sending a roots/list request with the cursor parameter set to this
+	 * @param meta See specification for notes on _meta usage
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ListRootsResult( // @formatter:off
 		@JsonProperty("roots") List roots,
-		@JsonProperty("nextCursor") String nextCursor) { // @formatter:on
+		@JsonProperty("nextCursor") String nextCursor,
+		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
 
 		public ListRootsResult(List roots) {
 			this(roots, null);
 		}
+
+		public ListRootsResult(List roots, String nextCursor) {
+			this(roots, nextCursor, null);
+		}
 	}
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index df7ab514f..fbbb4307e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -24,6 +24,7 @@
 
 /**
  * @author Christian Tzolov
+ * @author Anurag Pant
  */
 public class McpSchemaTests {
 
@@ -46,11 +47,12 @@ void testTextContent() throws Exception {
 	@Test
 	void testTextContentDeserialization() throws Exception {
 		McpSchema.TextContent textContent = mapper.readValue("""
-				{"type":"text","text":"XXX"}""", McpSchema.TextContent.class);
+				{"type":"text","text":"XXX","_meta":{"metaKey":"metaValue"}}""", McpSchema.TextContent.class);
 
 		assertThat(textContent).isNotNull();
 		assertThat(textContent.type()).isEqualTo("text");
 		assertThat(textContent.text()).isEqualTo("XXX");
+		assertThat(textContent.meta()).containsKey("metaKey");
 	}
 
 	@Test
@@ -78,11 +80,13 @@ void testImageContent() throws Exception {
 	@Test
 	void testImageContentDeserialization() throws Exception {
 		McpSchema.ImageContent imageContent = mapper.readValue("""
-				{"type":"image","data":"base64encodeddata","mimeType":"image/png"}""", McpSchema.ImageContent.class);
+				{"type":"image","data":"base64encodeddata","mimeType":"image/png","_meta":{"metaKey":"metaValue"}}""",
+				McpSchema.ImageContent.class);
 		assertThat(imageContent).isNotNull();
 		assertThat(imageContent.type()).isEqualTo("image");
 		assertThat(imageContent.data()).isEqualTo("base64encodeddata");
 		assertThat(imageContent.mimeType()).isEqualTo("image/png");
+		assertThat(imageContent.meta()).containsKey("metaKey");
 	}
 
 	@Test
@@ -100,11 +104,13 @@ void testAudioContent() throws Exception {
 	@Test
 	void testAudioContentDeserialization() throws Exception {
 		McpSchema.AudioContent audioContent = mapper.readValue("""
-				{"type":"audio","data":"base64encodeddata","mimeType":"audio/wav"}""", McpSchema.AudioContent.class);
+				{"type":"audio","data":"base64encodeddata","mimeType":"audio/wav","_meta":{"metaKey":"metaValue"}}""",
+				McpSchema.AudioContent.class);
 		assertThat(audioContent).isNotNull();
 		assertThat(audioContent.type()).isEqualTo("audio");
 		assertThat(audioContent.data()).isEqualTo("base64encodeddata");
 		assertThat(audioContent.mimeType()).isEqualTo("audio/wav");
+		assertThat(audioContent.meta()).containsKey("metaKey");
 	}
 
 	@Test
@@ -164,7 +170,7 @@ void testEmbeddedResource() throws Exception {
 	void testEmbeddedResourceDeserialization() throws Exception {
 		McpSchema.EmbeddedResource embeddedResource = mapper.readValue(
 				"""
-						{"type":"resource","resource":{"uri":"resource://test","mimeType":"text/plain","text":"Sample resource content"}}""",
+						{"type":"resource","resource":{"uri":"resource://test","mimeType":"text/plain","text":"Sample resource content"},"_meta":{"metaKey":"metaValue"}}""",
 				McpSchema.EmbeddedResource.class);
 		assertThat(embeddedResource).isNotNull();
 		assertThat(embeddedResource.type()).isEqualTo("resource");
@@ -172,6 +178,7 @@ void testEmbeddedResourceDeserialization() throws Exception {
 		assertThat(embeddedResource.resource().uri()).isEqualTo("resource://test");
 		assertThat(embeddedResource.resource().mimeType()).isEqualTo("text/plain");
 		assertThat(((TextResourceContents) embeddedResource.resource()).text()).isEqualTo("Sample resource content");
+		assertThat(embeddedResource.meta()).containsKey("metaKey");
 	}
 
 	@Test
@@ -194,7 +201,7 @@ void testEmbeddedResourceWithBlobContents() throws Exception {
 	void testEmbeddedResourceWithBlobContentsDeserialization() throws Exception {
 		McpSchema.EmbeddedResource embeddedResource = mapper.readValue(
 				"""
-						{"type":"resource","resource":{"uri":"resource://test","mimeType":"application/octet-stream","blob":"base64encodedblob"}}""",
+						{"type":"resource","resource":{"uri":"resource://test","mimeType":"application/octet-stream","blob":"base64encodedblob","_meta":{"metaKey":"metaValue"}}}""",
 				McpSchema.EmbeddedResource.class);
 		assertThat(embeddedResource).isNotNull();
 		assertThat(embeddedResource.type()).isEqualTo("resource");
@@ -203,12 +210,14 @@ void testEmbeddedResourceWithBlobContentsDeserialization() throws Exception {
 		assertThat(embeddedResource.resource().mimeType()).isEqualTo("application/octet-stream");
 		assertThat(((McpSchema.BlobResourceContents) embeddedResource.resource()).blob())
 			.isEqualTo("base64encodedblob");
+		assertThat(((McpSchema.BlobResourceContents) embeddedResource.resource()).meta()).containsKey("metaKey");
 	}
 
 	@Test
 	void testResourceLink() throws Exception {
 		McpSchema.ResourceLink resourceLink = new McpSchema.ResourceLink("main.rs", "Main file",
-				"file:///project/src/main.rs", "Primary application entry point", "text/x-rust", null, null);
+				"file:///project/src/main.rs", "Primary application entry point", "text/x-rust", null, null,
+				Map.of("metaKey", "metaValue"));
 		String value = mapper.writeValueAsString(resourceLink);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -216,14 +225,14 @@ void testResourceLink() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"type":"resource_link","name":"main.rs","title":"Main file","uri":"file:///project/src/main.rs","description":"Primary application entry point","mimeType":"text/x-rust"}"""));
+							{"type":"resource_link","name":"main.rs","title":"Main file","uri":"file:///project/src/main.rs","description":"Primary application entry point","mimeType":"text/x-rust","_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
 	void testResourceLinkDeserialization() throws Exception {
 		McpSchema.ResourceLink resourceLink = mapper.readValue(
 				"""
-						{"type":"resource_link","name":"main.rs","uri":"file:///project/src/main.rs","description":"Primary application entry point","mimeType":"text/x-rust"}""",
+						{"type":"resource_link","name":"main.rs","uri":"file:///project/src/main.rs","description":"Primary application entry point","mimeType":"text/x-rust","_meta":{"metaKey":"metaValue"}}""",
 				McpSchema.ResourceLink.class);
 		assertThat(resourceLink).isNotNull();
 		assertThat(resourceLink.type()).isEqualTo("resource_link");
@@ -231,6 +240,7 @@ void testResourceLinkDeserialization() throws Exception {
 		assertThat(resourceLink.uri()).isEqualTo("file:///project/src/main.rs");
 		assertThat(resourceLink.description()).isEqualTo("Primary application entry point");
 		assertThat(resourceLink.mimeType()).isEqualTo("text/x-rust");
+		assertThat(resourceLink.meta()).containsEntry("metaKey", "metaValue");
 	}
 
 	// JSON-RPC Message Types Tests
@@ -307,8 +317,10 @@ void testInitializeRequest() throws Exception {
 			.build();
 
 		McpSchema.Implementation clientInfo = new McpSchema.Implementation("test-client", "1.0.0");
+		Map meta = Map.of("metaKey", "metaValue");
 
-		McpSchema.InitializeRequest request = new McpSchema.InitializeRequest("2024-11-05", capabilities, clientInfo);
+		McpSchema.InitializeRequest request = new McpSchema.InitializeRequest("2024-11-05", capabilities, clientInfo,
+				meta);
 
 		String value = mapper.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -316,7 +328,7 @@ void testInitializeRequest() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"protocolVersion":"2024-11-05","capabilities":{"roots":{"listChanged":true},"sampling":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}"""));
+							{"protocolVersion":"2024-11-05","capabilities":{"roots":{"listChanged":true},"sampling":{}},"clientInfo":{"name":"test-client","version":"1.0.0"},"_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
@@ -373,6 +385,7 @@ void testResourceBuilder() throws Exception {
 			.mimeType("text/plain")
 			.size(256L)
 			.annotations(annotations)
+			.meta(Map.of("metaKey", "metaValue"))
 			.build();
 
 		String value = mapper.writeValueAsString(resource);
@@ -381,7 +394,7 @@ void testResourceBuilder() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"uri":"resource://test","name":"Test Resource","description":"A test resource","mimeType":"text/plain","size":256,"annotations":{"audience":["user","assistant"],"priority":0.8}}"""));
+							{"uri":"resource://test","name":"Test Resource","description":"A test resource","mimeType":"text/plain","size":256,"annotations":{"audience":["user","assistant"],"priority":0.8},"_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
@@ -417,9 +430,10 @@ void testResourceBuilderNameRequired() {
 	@Test
 	void testResourceTemplate() throws Exception {
 		McpSchema.Annotations annotations = new McpSchema.Annotations(Arrays.asList(McpSchema.Role.USER), 0.5);
+		Map meta = Map.of("metaKey", "metaValue");
 
 		McpSchema.ResourceTemplate template = new McpSchema.ResourceTemplate("resource://{param}/test", "Test Template",
-				"Test Template", "A test resource template", "text/plain", annotations);
+				"Test Template", "A test resource template", "text/plain", annotations, meta);
 
 		String value = mapper.writeValueAsString(template);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -427,7 +441,7 @@ void testResourceTemplate() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"uriTemplate":"resource://{param}/test","name":"Test Template","title":"Test Template","description":"A test resource template","mimeType":"text/plain","annotations":{"audience":["user"],"priority":0.5}}"""));
+							{"uriTemplate":"resource://{param}/test","name":"Test Template","title":"Test Template","description":"A test resource template","mimeType":"text/plain","annotations":{"audience":["user"],"priority":0.5},"_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
@@ -438,8 +452,10 @@ void testListResourcesResult() throws Exception {
 		McpSchema.Resource resource2 = new McpSchema.Resource("resource://test2", "Test Resource 2",
 				"Second test resource", "application/json", null);
 
+		Map meta = Map.of("metaKey", "metaValue");
+
 		McpSchema.ListResourcesResult result = new McpSchema.ListResourcesResult(Arrays.asList(resource1, resource2),
-				"next-cursor");
+				"next-cursor", meta);
 
 		String value = mapper.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -447,7 +463,7 @@ void testListResourcesResult() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"resources":[{"uri":"resource://test1","name":"Test Resource 1","description":"First test resource","mimeType":"text/plain"},{"uri":"resource://test2","name":"Test Resource 2","description":"Second test resource","mimeType":"application/json"}],"nextCursor":"next-cursor"}"""));
+							{"resources":[{"uri":"resource://test1","name":"Test Resource 1","description":"First test resource","mimeType":"text/plain"},{"uri":"resource://test2","name":"Test Resource 2","description":"Second test resource","mimeType":"application/json"}],"nextCursor":"next-cursor","_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
@@ -472,14 +488,15 @@ void testListResourceTemplatesResult() throws Exception {
 
 	@Test
 	void testReadResourceRequest() throws Exception {
-		McpSchema.ReadResourceRequest request = new McpSchema.ReadResourceRequest("resource://test");
+		McpSchema.ReadResourceRequest request = new McpSchema.ReadResourceRequest("resource://test",
+				Map.of("metaKey", "metaValue"));
 
 		String value = mapper.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
 			.isEqualTo(json("""
-					{"uri":"resource://test"}"""));
+					{"uri":"resource://test","_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
@@ -520,7 +537,8 @@ void testReadResourceResult() throws Exception {
 		McpSchema.BlobResourceContents contents2 = new McpSchema.BlobResourceContents("resource://test2",
 				"application/octet-stream", "base64encodedblob");
 
-		McpSchema.ReadResourceResult result = new McpSchema.ReadResourceResult(Arrays.asList(contents1, contents2));
+		McpSchema.ReadResourceResult result = new McpSchema.ReadResourceResult(Arrays.asList(contents1, contents2),
+				Map.of("metaKey", "metaValue"));
 
 		String value = mapper.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -528,7 +546,7 @@ void testReadResourceResult() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"contents":[{"uri":"resource://test1","mimeType":"text/plain","text":"Sample text content"},{"uri":"resource://test2","mimeType":"application/octet-stream","blob":"base64encodedblob"}]}"""));
+							{"contents":[{"uri":"resource://test1","mimeType":"text/plain","text":"Sample text content"},{"uri":"resource://test2","mimeType":"application/octet-stream","blob":"base64encodedblob"}],"_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	// Prompt Tests
@@ -541,7 +559,7 @@ void testPrompt() throws Exception {
 				false);
 
 		McpSchema.Prompt prompt = new McpSchema.Prompt("test-prompt", "Test Prompt", "A test prompt",
-				Arrays.asList(arg1, arg2));
+				Arrays.asList(arg1, arg2), Map.of("metaKey", "metaValue"));
 
 		String value = mapper.writeValueAsString(prompt);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -549,7 +567,7 @@ void testPrompt() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"name":"test-prompt","title":"Test Prompt","description":"A test prompt","arguments":[{"name":"arg1","title":"First argument","description":"First argument","required":true},{"name":"arg2","title":"Second argument","description":"Second argument","required":false}]}"""));
+							{"name":"test-prompt","title":"Test Prompt","description":"A test prompt","arguments":[{"name":"arg1","title":"First argument","description":"First argument","required":true},{"name":"arg2","title":"Second argument","description":"Second argument","required":false}],"_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
@@ -805,6 +823,34 @@ void testToolWithComplexSchema() throws Exception {
 		assertThat(deserializedTool.inputSchema().defs()).containsKey("Address");
 	}
 
+	@Test
+	void testToolWithMeta() throws Exception {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {
+							"type": "string"
+						},
+						"value": {
+							"type": "number"
+						}
+					},
+					"required": ["name"]
+				}
+				""";
+
+		McpSchema.JsonSchema schema = mapper.readValue(schemaJson, McpSchema.JsonSchema.class);
+		Map meta = Map.of("metaKey", "metaValue");
+
+		McpSchema.Tool tool = new McpSchema.Tool("addressTool", "addressTool", "Handles addresses", schema, null, null,
+				meta);
+
+		// Verify that meta value was preserved
+		assertThat(tool.meta()).isNotNull();
+		assertThat(tool.meta()).containsKey("metaKey");
+	}
+
 	@Test
 	void testToolWithAnnotations() throws Exception {
 		String schemaJson = """
@@ -1510,14 +1556,14 @@ void testCompleteRequestWithMeta() throws Exception {
 
 	@Test
 	void testRoot() throws Exception {
-		McpSchema.Root root = new McpSchema.Root("file:///path/to/root", "Test Root");
+		McpSchema.Root root = new McpSchema.Root("file:///path/to/root", "Test Root", Map.of("metaKey", "metaValue"));
 
 		String value = mapper.writeValueAsString(root);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
 			.isEqualTo(json("""
-					{"uri":"file:///path/to/root","name":"Test Root"}"""));
+					{"uri":"file:///path/to/root","name":"Test Root","_meta":{"metaKey":"metaValue"}}"""));
 	}
 
 	@Test
@@ -1544,7 +1590,7 @@ void testListRootsResult() throws Exception {
 	@Test
 	void testProgressNotificationWithMessage() throws Exception {
 		McpSchema.ProgressNotification notification = new McpSchema.ProgressNotification("progress-token-123", 0.5, 1.0,
-				"Processing file 1 of 2");
+				"Processing file 1 of 2", Map.of("key", "value"));
 
 		String value = mapper.writeValueAsString(notification);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -1552,19 +1598,21 @@ void testProgressNotificationWithMessage() throws Exception {
 			.isObject()
 			.isEqualTo(
 					json("""
-							{"progressToken":"progress-token-123","progress":0.5,"total":1.0,"message":"Processing file 1 of 2"}"""));
+							{"progressToken":"progress-token-123","progress":0.5,"total":1.0,"message":"Processing file 1 of 2","_meta":{"key":"value"}}"""));
 	}
 
 	@Test
 	void testProgressNotificationDeserialization() throws Exception {
-		McpSchema.ProgressNotification notification = mapper.readValue("""
-				{"progressToken":"token-456","progress":0.75,"total":1.0,"message":"Almost done"}""",
+		McpSchema.ProgressNotification notification = mapper.readValue(
+				"""
+						{"progressToken":"token-456","progress":0.75,"total":1.0,"message":"Almost done","_meta":{"key":"value"}}""",
 				McpSchema.ProgressNotification.class);
 
 		assertThat(notification.progressToken()).isEqualTo("token-456");
 		assertThat(notification.progress()).isEqualTo(0.75);
 		assertThat(notification.total()).isEqualTo(1.0);
 		assertThat(notification.message()).isEqualTo("Almost done");
+		assertThat(notification.meta()).containsEntry("key", "value");
 	}
 
 	@Test

From b04c30b60e058547da1eda6a416fbdf3d6833f12 Mon Sep 17 00:00:00 2001
From: JiHwan Oh 
Date: Thu, 17 Jul 2025 10:31:34 +0900
Subject: [PATCH 014/125] feat: Add progress notification support for MCP
 operations (#407)

Implement progress tracking for long-running operations with:
- New ProgressNotification schema and client/server support
- Progress consumer handlers in sync/async client builders
- Server exchange methods for sending progress updates
- Comprehensive integration tests
- Backwards compatibility maintained
- Add additional tests

Signed-off-by: Christian Tzolov 
---
 .../WebFluxSseIntegrationTests.java           | 107 ++++++++++++++++++
 .../client/AbstractMcpAsyncClientTests.java   |  40 ++++++-
 .../client/AbstractMcpSyncClientTests.java    |  47 ++++++++
 .../client/McpAsyncClient.java                |  35 ++++++
 .../client/McpClient.java                     |  72 +++++++++++-
 .../client/McpClientFeatures.java             |  51 ++++++++-
 .../server/McpAsyncServerExchange.java        |  13 +++
 .../server/McpServerFeatures.java             |   2 +-
 .../server/McpSyncServerExchange.java         |   9 ++
 .../modelcontextprotocol/spec/McpSchema.java  |   5 +-
 .../client/AbstractMcpAsyncClientTests.java   |  38 +++++++
 .../client/AbstractMcpSyncClientTests.java    |  47 ++++++++
 ...rverTransportProviderIntegrationTests.java |  77 ++++++++++++-
 13 files changed, 535 insertions(+), 8 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index 9ef2855b1..23ddf6173 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -1016,6 +1016,113 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 		mcpServer.close();
 	}
 
+	// ---------------------------------------
+	// Progress Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testProgressNotification(String clientType) throws InterruptedException {
+		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
+											// token
+		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
+		// Create a list to store received logging notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that sends logging notifications
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(McpSchema.Tool.builder()
+				.name("progress-test")
+				.description("Test progress notifications")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications
+				var progressToken = (String) request.meta().get("progressToken");
+
+				return exchange
+					.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.0, 1.0, "Processing started"))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Processing data")))
+					.then(// Send a progress notification with another progress value
+							// should
+							exchange.progressNotification(new McpSchema.ProgressNotification("another-progress-token",
+									0.0, 1.0, "Another processing started")))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
+					.thenReturn(new CallToolResult(("Progress test completed"), false));
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client with progress notification handler
+				var mcpClient = clientBuilder.progressConsumer(notification -> {
+					receivedNotifications.add(notification);
+					latch.countDown();
+				}).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that sends progress notifications
+			McpSchema.CallToolRequest callToolRequest = McpSchema.CallToolRequest.builder()
+				.name("progress-test")
+				.meta(Map.of("progressToken", "test-progress-token"))
+				.build();
+			CallToolResult result = mcpClient.callTool(callToolRequest);
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
+
+			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
+
+			// Should have received 3 notifications
+			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
+
+			Map notificationMap = receivedNotifications.stream()
+				.collect(Collectors.toMap(n -> n.message(), n -> n));
+
+			// First notification should be 0.0/1.0 progress
+			assertThat(notificationMap.get("Processing started").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing started").message()).isEqualTo("Processing started");
+
+			// Second notification should be 0.5/1.0 progress
+			assertThat(notificationMap.get("Processing data").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing data").progress()).isEqualTo(0.5);
+			assertThat(notificationMap.get("Processing data").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing data").message()).isEqualTo("Processing data");
+
+			// Third notification should be another progress token with 0.0/1.0 progress
+			assertThat(notificationMap.get("Another processing started").progressToken())
+				.isEqualTo("another-progress-token");
+			assertThat(notificationMap.get("Another processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Another processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Another processing started").message())
+				.isEqualTo("Another processing started");
+
+			// Fourth notification should be 1.0/1.0 progress
+			assertThat(notificationMap.get("Processing completed").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing completed").progress()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
+		}
+		finally {
+			mcpServer.close();
+		}
+	}
+
 	// ---------------------------------------
 	// Completion Tests
 	// ---------------------------------------
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 659a3222e..067fbac2c 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -12,8 +12,10 @@
 
 import java.time.Duration;
 import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
@@ -49,6 +51,7 @@
 import io.modelcontextprotocol.spec.McpTransport;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
+import reactor.core.publisher.Sinks;
 import reactor.test.StepVerifier;
 
 /**
@@ -420,7 +423,7 @@ void testListAllPromptsReturnsImmutableList() {
 				.consumeNextWith(result -> {
 					assertThat(result.prompts()).isNotNull();
 					// Verify that the returned list is immutable
-					assertThatThrownBy(() -> result.prompts().add(new Prompt("test", "Test", "test", null)))
+					assertThatThrownBy(() -> result.prompts().add(new Prompt("test", "test", "test", null)))
 						.isInstanceOf(UnsupportedOperationException.class);
 				})
 				.verifyComplete();
@@ -792,4 +795,39 @@ void testSampling() {
 			});
 	}
 
+	// ---------------------------------------
+	// Progress Notification Tests
+	// ---------------------------------------
+
+	@Test
+	void testProgressConsumer() {
+		Sinks.Many sink = Sinks.many().unicast().onBackpressureBuffer();
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		withClient(createMcpTransport(), builder -> builder.progressConsumer(notification -> {
+			receivedNotifications.add(notification);
+			sink.tryEmitNext(notification);
+			return Mono.empty();
+		}), client -> {
+			StepVerifier.create(client.initialize()).expectNextMatches(Objects::nonNull).verifyComplete();
+
+			// Call a tool that sends progress notifications
+			CallToolRequest request = CallToolRequest.builder()
+				.name("longRunningOperation")
+				.arguments(Map.of("duration", 1, "steps", 2))
+				.progressToken("test-token")
+				.build();
+
+			StepVerifier.create(client.callTool(request)).consumeNextWith(result -> {
+				assertThat(result).isNotNull();
+			}).verifyComplete();
+
+			// Use StepVerifier to verify the progress notifications via the sink
+			StepVerifier.create(sink.asFlux()).expectNextCount(2).thenCancel().verify(Duration.ofSeconds(3));
+
+			assertThat(receivedNotifications).hasSize(2);
+			assertThat(receivedNotifications.get(0).progressToken()).isEqualTo("test-token");
+		});
+	}
+
 }
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 7736c233c..175a0107c 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -13,6 +13,9 @@
 import java.time.Duration;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
@@ -648,4 +651,48 @@ void testSampling() {
 			});
 	}
 
+	// ---------------------------------------
+	// Progress Notification Tests
+	// ---------------------------------------
+
+	@Test
+	void testProgressConsumer() {
+		AtomicInteger progressNotificationCount = new AtomicInteger(0);
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+		CountDownLatch latch = new CountDownLatch(2);
+
+		withClient(createMcpTransport(), builder -> builder.progressConsumer(notification -> {
+			System.out.println("Received progress notification: " + notification);
+			receivedNotifications.add(notification);
+			progressNotificationCount.incrementAndGet();
+			latch.countDown();
+		}), client -> {
+			client.initialize();
+
+			// Call a tool that sends progress notifications
+			CallToolRequest request = CallToolRequest.builder()
+				.name("longRunningOperation")
+				.arguments(Map.of("duration", 1, "steps", 2))
+				.progressToken("test-token")
+				.build();
+
+			CallToolResult result = client.callTool(request);
+
+			assertThat(result).isNotNull();
+
+			try {
+				// Wait for progress notifications to be processed
+				latch.await(3, TimeUnit.SECONDS);
+			}
+			catch (InterruptedException e) {
+				e.printStackTrace();
+			}
+
+			assertThat(progressNotificationCount.get()).isEqualTo(2);
+
+			assertThat(receivedNotifications).isNotEmpty();
+			assertThat(receivedNotifications.get(0).progressToken()).isEqualTo("test-token");
+		});
+	}
+
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index cf8142c68..9e861deba 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -100,6 +100,9 @@ public class McpAsyncClient {
 	public static final TypeReference LOGGING_MESSAGE_NOTIFICATION_TYPE_REF = new TypeReference<>() {
 	};
 
+	public static final TypeReference PROGRESS_NOTIFICATION_TYPE_REF = new TypeReference<>() {
+	};
+
 	/**
 	 * Client capabilities.
 	 */
@@ -253,6 +256,16 @@ public class McpAsyncClient {
 		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_MESSAGE,
 				asyncLoggingNotificationHandler(loggingConsumersFinal));
 
+		// Utility Progress Notification
+		List>> progressConsumersFinal = new ArrayList<>();
+		progressConsumersFinal
+			.add((notification) -> Mono.fromRunnable(() -> logger.debug("Progress: {}", notification)));
+		if (!Utils.isEmpty(features.progressConsumers())) {
+			progressConsumersFinal.addAll(features.progressConsumers());
+		}
+		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_PROGRESS,
+				asyncProgressNotificationHandler(progressConsumersFinal));
+
 		this.initializer = new LifecycleInitializer(clientCapabilities, clientInfo,
 				List.of(McpSchema.LATEST_PROTOCOL_VERSION), initializationTimeout,
 				ctx -> new McpClientSession(requestTimeout, transport, requestHandlers, notificationHandlers,
@@ -846,6 +859,28 @@ public Mono setLoggingLevel(LoggingLevel loggingLevel) {
 		});
 	}
 
+	/**
+	 * Create a notification handler for progress notifications from the server. This
+	 * handler automatically distributes progress notifications to all registered
+	 * consumers.
+	 * @param progressConsumers List of consumers that will be notified when a progress
+	 * message is received. Each consumer receives the progress notification.
+	 * @return A NotificationHandler that processes progress notifications by distributing
+	 * the message to all registered consumers
+	 */
+	private NotificationHandler asyncProgressNotificationHandler(
+			List>> progressConsumers) {
+
+		return params -> {
+			McpSchema.ProgressNotification progressNotification = transport.unmarshalFrom(params,
+					PROGRESS_NOTIFICATION_TYPE_REF);
+
+			return Flux.fromIterable(progressConsumers)
+				.flatMap(consumer -> consumer.apply(progressNotification))
+				.then();
+		};
+	}
+
 	/**
 	 * This method is package-private and used for test only. Should not be called by user
 	 * code.
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java
index d8925b005..c8af28ac1 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java
@@ -177,6 +177,8 @@ class SyncSpec {
 
 		private final List> loggingConsumers = new ArrayList<>();
 
+		private final List> progressConsumers = new ArrayList<>();
+
 		private Function samplingHandler;
 
 		private Function elicitationHandler;
@@ -377,6 +379,36 @@ public SyncSpec loggingConsumers(List progressConsumer) {
+			Assert.notNull(progressConsumer, "Progress consumer must not be null");
+			this.progressConsumers.add(progressConsumer);
+			return this;
+		}
+
+		/**
+		 * Adds a multiple consumers to be notified of progress notifications from the
+		 * server. This allows the client to track long-running operations and provide
+		 * feedback to users.
+		 * @param progressConsumers A list of consumers that receives progress
+		 * notifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if progressConsumer is null
+		 */
+		public SyncSpec progressConsumers(List> progressConsumers) {
+			Assert.notNull(progressConsumers, "Progress consumers must not be null");
+			this.progressConsumers.addAll(progressConsumers);
+			return this;
+		}
+
 		/**
 		 * Create an instance of {@link McpSyncClient} with the provided configurations or
 		 * sensible defaults.
@@ -385,7 +417,8 @@ public SyncSpec loggingConsumers(List>> loggingConsumers = new ArrayList<>();
 
+		private final List>> progressConsumers = new ArrayList<>();
+
 		private Function> samplingHandler;
 
 		private Function> elicitationHandler;
@@ -654,6 +689,37 @@ public AsyncSpec loggingConsumers(
 			return this;
 		}
 
+		/**
+		 * Adds a consumer to be notified of progress notifications from the server. This
+		 * allows the client to track long-running operations and provide feedback to
+		 * users.
+		 * @param progressConsumer A consumer that receives progress notifications. Must
+		 * not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if progressConsumer is null
+		 */
+		public AsyncSpec progressConsumer(Function> progressConsumer) {
+			Assert.notNull(progressConsumer, "Progress consumer must not be null");
+			this.progressConsumers.add(progressConsumer);
+			return this;
+		}
+
+		/**
+		 * Adds a multiple consumers to be notified of progress notifications from the
+		 * server. This allows the client to track long-running operations and provide
+		 * feedback to users.
+		 * @param progressConsumers A list of consumers that receives progress
+		 * notifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if progressConsumer is null
+		 */
+		public AsyncSpec progressConsumers(
+				List>> progressConsumers) {
+			Assert.notNull(progressConsumers, "Progress consumers must not be null");
+			this.progressConsumers.addAll(progressConsumers);
+			return this;
+		}
+
 		/**
 		 * Create an instance of {@link McpAsyncClient} with the provided configurations
 		 * or sensible defaults.
@@ -663,8 +729,8 @@ public McpAsyncClient build() {
 			return new McpAsyncClient(this.transport, this.requestTimeout, this.initializationTimeout,
 					new McpClientFeatures.Async(this.clientInfo, this.capabilities, this.roots,
 							this.toolsChangeConsumers, this.resourcesChangeConsumers, this.resourcesUpdateConsumers,
-							this.promptsChangeConsumers, this.loggingConsumers, this.samplingHandler,
-							this.elicitationHandler));
+							this.promptsChangeConsumers, this.loggingConsumers, this.progressConsumers,
+							this.samplingHandler, this.elicitationHandler));
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
index bd1a0985a..3b6550765 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
@@ -59,6 +59,7 @@ class McpClientFeatures {
 	 * @param resourcesChangeConsumers the resources change consumers.
 	 * @param promptsChangeConsumers the prompts change consumers.
 	 * @param loggingConsumers the logging consumers.
+	 * @param progressConsumers the progress consumers.
 	 * @param samplingHandler the sampling handler.
 	 * @param elicitationHandler the elicitation handler.
 	 */
@@ -68,6 +69,7 @@ record Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 			List, Mono>> resourcesUpdateConsumers,
 			List, Mono>> promptsChangeConsumers,
 			List>> loggingConsumers,
+			List>> progressConsumers,
 			Function> samplingHandler,
 			Function> elicitationHandler) {
 
@@ -79,6 +81,7 @@ record Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 		 * @param resourcesChangeConsumers the resources change consumers.
 		 * @param promptsChangeConsumers the prompts change consumers.
 		 * @param loggingConsumers the logging consumers.
+		 * @param progressConsumers the progress consumers.
 		 * @param samplingHandler the sampling handler.
 		 * @param elicitationHandler the elicitation handler.
 		 */
@@ -89,6 +92,7 @@ public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 				List, Mono>> resourcesUpdateConsumers,
 				List, Mono>> promptsChangeConsumers,
 				List>> loggingConsumers,
+				List>> progressConsumers,
 				Function> samplingHandler,
 				Function> elicitationHandler) {
 
@@ -106,10 +110,28 @@ public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 			this.resourcesUpdateConsumers = resourcesUpdateConsumers != null ? resourcesUpdateConsumers : List.of();
 			this.promptsChangeConsumers = promptsChangeConsumers != null ? promptsChangeConsumers : List.of();
 			this.loggingConsumers = loggingConsumers != null ? loggingConsumers : List.of();
+			this.progressConsumers = progressConsumers != null ? progressConsumers : List.of();
 			this.samplingHandler = samplingHandler;
 			this.elicitationHandler = elicitationHandler;
 		}
 
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes.
+		 */
+		public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
+				Map roots,
+				List, Mono>> toolsChangeConsumers,
+				List, Mono>> resourcesChangeConsumers,
+				List, Mono>> resourcesUpdateConsumers,
+				List, Mono>> promptsChangeConsumers,
+				List>> loggingConsumers,
+				Function> samplingHandler,
+				Function> elicitationHandler) {
+			this(clientInfo, clientCapabilities, roots, toolsChangeConsumers, resourcesChangeConsumers,
+					resourcesUpdateConsumers, promptsChangeConsumers, loggingConsumers, List.of(), samplingHandler,
+					elicitationHandler);
+		}
+
 		/**
 		 * Convert a synchronous specification into an asynchronous one and provide
 		 * blocking code offloading to prevent accidental blocking of the non-blocking
@@ -149,6 +171,12 @@ public static Async fromSync(Sync syncSpec) {
 					.subscribeOn(Schedulers.boundedElastic()));
 			}
 
+			List>> progressConsumers = new ArrayList<>();
+			for (Consumer consumer : syncSpec.progressConsumers()) {
+				progressConsumers.add(l -> Mono.fromRunnable(() -> consumer.accept(l))
+					.subscribeOn(Schedulers.boundedElastic()));
+			}
+
 			Function> samplingHandler = r -> Mono
 				.fromCallable(() -> syncSpec.samplingHandler().apply(r))
 				.subscribeOn(Schedulers.boundedElastic());
@@ -159,7 +187,7 @@ public static Async fromSync(Sync syncSpec) {
 
 			return new Async(syncSpec.clientInfo(), syncSpec.clientCapabilities(), syncSpec.roots(),
 					toolsChangeConsumers, resourcesChangeConsumers, resourcesUpdateConsumers, promptsChangeConsumers,
-					loggingConsumers, samplingHandler, elicitationHandler);
+					loggingConsumers, progressConsumers, samplingHandler, elicitationHandler);
 		}
 	}
 
@@ -174,6 +202,7 @@ public static Async fromSync(Sync syncSpec) {
 	 * @param resourcesChangeConsumers the resources change consumers.
 	 * @param promptsChangeConsumers the prompts change consumers.
 	 * @param loggingConsumers the logging consumers.
+	 * @param progressConsumers the progress consumers.
 	 * @param samplingHandler the sampling handler.
 	 * @param elicitationHandler the elicitation handler.
 	 */
@@ -183,6 +212,7 @@ public record Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabili
 			List>> resourcesUpdateConsumers,
 			List>> promptsChangeConsumers,
 			List> loggingConsumers,
+			List> progressConsumers,
 			Function samplingHandler,
 			Function elicitationHandler) {
 
@@ -196,6 +226,7 @@ public record Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabili
 		 * @param resourcesUpdateConsumers the resource update consumers.
 		 * @param promptsChangeConsumers the prompts change consumers.
 		 * @param loggingConsumers the logging consumers.
+		 * @param progressConsumers the progress consumers.
 		 * @param samplingHandler the sampling handler.
 		 * @param elicitationHandler the elicitation handler.
 		 */
@@ -205,6 +236,7 @@ public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities cl
 				List>> resourcesUpdateConsumers,
 				List>> promptsChangeConsumers,
 				List> loggingConsumers,
+				List> progressConsumers,
 				Function samplingHandler,
 				Function elicitationHandler) {
 
@@ -222,9 +254,26 @@ public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities cl
 			this.resourcesUpdateConsumers = resourcesUpdateConsumers != null ? resourcesUpdateConsumers : List.of();
 			this.promptsChangeConsumers = promptsChangeConsumers != null ? promptsChangeConsumers : List.of();
 			this.loggingConsumers = loggingConsumers != null ? loggingConsumers : List.of();
+			this.progressConsumers = progressConsumers != null ? progressConsumers : List.of();
 			this.samplingHandler = samplingHandler;
 			this.elicitationHandler = elicitationHandler;
 		}
+
+		/**
+		 * @deprecated Only exists for backwards-compatibility purposes.
+		 */
+		public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
+				Map roots, List>> toolsChangeConsumers,
+				List>> resourcesChangeConsumers,
+				List>> resourcesUpdateConsumers,
+				List>> promptsChangeConsumers,
+				List> loggingConsumers,
+				Function samplingHandler,
+				Function elicitationHandler) {
+			this(clientInfo, clientCapabilities, roots, toolsChangeConsumers, resourcesChangeConsumers,
+					resourcesUpdateConsumers, promptsChangeConsumers, loggingConsumers, List.of(), samplingHandler,
+					elicitationHandler);
+		}
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
index e56c695fa..c0923e10e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
@@ -177,6 +177,19 @@ public Mono loggingNotification(LoggingMessageNotification loggingMessageN
 		});
 	}
 
+	/**
+	 * Sends a notification to the client that the current progress status has changed for
+	 * long-running operations.
+	 * @param progressNotification The progress notification to send
+	 * @return A Mono that completes when the notification has been sent
+	 */
+	public Mono progressNotification(McpSchema.ProgressNotification progressNotification) {
+		if (progressNotification == null) {
+			return Mono.error(new McpError("Progress notification must not be null"));
+		}
+		return this.session.sendNotification(McpSchema.METHOD_NOTIFICATION_PROGRESS, progressNotification);
+	}
+
 	/**
 	 * Sends a ping request to the client.
 	 * @return A Mono that completes with clients's ping response
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
index 3ce599c8b..12edfb341 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
@@ -209,7 +209,7 @@ record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities se
 	 * represents a specific capability.
 	 *
 	 * @param tool The tool definition including name, description, and parameter schema
-	 * @param call Deprecated. Uset he {@link AsyncToolSpecification#callHandler} instead.
+	 * @param call Deprecated. Use the {@link AsyncToolSpecification#callHandler} instead.
 	 * @param callHandler The function that implements the tool's logic, receiving a
 	 * {@link McpAsyncServerExchange} and a
 	 * {@link io.modelcontextprotocol.spec.McpSchema.CallToolRequest} and returning
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
index 4b9a3777b..dad1e4c19 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
@@ -107,6 +107,15 @@ public void loggingNotification(LoggingMessageNotification loggingMessageNotific
 		this.exchange.loggingNotification(loggingMessageNotification).block();
 	}
 
+	/**
+	 * Sends a notification to the client that the current progress status has changed for
+	 * long-running operations.
+	 * @param progressNotification The progress notification to send
+	 */
+	public void progressNotification(McpSchema.ProgressNotification progressNotification) {
+		this.exchange.progressNotification(progressNotification).block();
+	}
+
 	/**
 	 * Sends a synchronous ping request to the client.
 	 * @return
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 75deb5a0f..5ba28cabd 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -61,6 +61,8 @@ private McpSchema() {
 
 	public static final String METHOD_PING = "ping";
 
+	public static final String METHOD_NOTIFICATION_PROGRESS = "notifications/progress";
+
 	// Tool Methods
 	public static final String METHOD_TOOLS_LIST = "tools/list";
 
@@ -1388,7 +1390,8 @@ private static JsonSchema parseSchema(String schema) {
 	 * tools/list.
 	 * @param arguments Arguments to pass to the tool. These must conform to the tool's
 	 * input schema.
-	 * @param meta See specification for notes on _meta usage
+	 * @param meta Optional metadata about the request. This can include additional
+	 * information like `progressToken`
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 154937d21..e912e1dd6 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -12,8 +12,10 @@
 
 import java.time.Duration;
 import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
@@ -49,6 +51,7 @@
 import io.modelcontextprotocol.spec.McpTransport;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
+import reactor.core.publisher.Sinks;
 import reactor.test.StepVerifier;
 
 /**
@@ -793,4 +796,39 @@ void testSampling() {
 			});
 	}
 
+	// ---------------------------------------
+	// Progress Notification Tests
+	// ---------------------------------------
+
+	@Test
+	void testProgressConsumer() {
+		Sinks.Many sink = Sinks.many().unicast().onBackpressureBuffer();
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		withClient(createMcpTransport(), builder -> builder.progressConsumer(notification -> {
+			receivedNotifications.add(notification);
+			sink.tryEmitNext(notification);
+			return Mono.empty();
+		}), client -> {
+			StepVerifier.create(client.initialize()).expectNextMatches(Objects::nonNull).verifyComplete();
+
+			// Call a tool that sends progress notifications
+			CallToolRequest request = CallToolRequest.builder()
+				.name("longRunningOperation")
+				.arguments(Map.of("duration", 1, "steps", 2))
+				.progressToken("test-token")
+				.build();
+
+			StepVerifier.create(client.callTool(request)).consumeNextWith(result -> {
+				assertThat(result).isNotNull();
+			}).verifyComplete();
+
+			// Use StepVerifier to verify the progress notifications via the sink
+			StepVerifier.create(sink.asFlux()).expectNextCount(2).thenCancel().verify(Duration.ofSeconds(3));
+
+			assertThat(receivedNotifications).hasSize(2);
+			assertThat(receivedNotifications.get(0).progressToken()).isEqualTo("test-token");
+		});
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 6cb694678..c74255060 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -13,6 +13,9 @@
 import java.time.Duration;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
@@ -649,4 +652,48 @@ void testSampling() {
 			});
 	}
 
+	// ---------------------------------------
+	// Progress Notification Tests
+	// ---------------------------------------
+
+	@Test
+	void testProgressConsumer() {
+		AtomicInteger progressNotificationCount = new AtomicInteger(0);
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+		CountDownLatch latch = new CountDownLatch(2);
+
+		withClient(createMcpTransport(), builder -> builder.progressConsumer(notification -> {
+			System.out.println("Received progress notification: " + notification);
+			receivedNotifications.add(notification);
+			progressNotificationCount.incrementAndGet();
+			latch.countDown();
+		}), client -> {
+			client.initialize();
+
+			// Call a tool that sends progress notifications
+			CallToolRequest request = CallToolRequest.builder()
+				.name("longRunningOperation")
+				.arguments(Map.of("duration", 1, "steps", 2))
+				.progressToken("test-token")
+				.build();
+
+			CallToolResult result = client.callTool(request);
+
+			assertThat(result).isNotNull();
+
+			try {
+				// Wait for progress notifications to be processed
+				latch.await(3, TimeUnit.SECONDS);
+			}
+			catch (InterruptedException e) {
+				e.printStackTrace();
+			}
+
+			assertThat(progressNotificationCount.get()).isEqualTo(2);
+
+			assertThat(receivedNotifications).isNotEmpty();
+			assertThat(receivedNotifications.get(0).progressToken()).isEqualTo("test-token");
+		});
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
index 66f33fb67..b04ecb3c4 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
@@ -7,6 +7,7 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
@@ -907,7 +908,7 @@ void testInitialize() {
 	@Test
 	void testLoggingNotification() {
 		// Create a list to store received logging notifications
-		List receivedNotifications = new ArrayList<>();
+		List receivedNotifications = new CopyOnWriteArrayList<>();
 
 		// Create server with a tool that sends logging notifications
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
@@ -1020,6 +1021,80 @@ void testLoggingNotification() {
 		mcpServer.close();
 	}
 
+	// ---------------------------------------
+	// Progress Tests
+	// ---------------------------------------
+	@Test
+	void testProgressNotification() {
+		// Create a list to store received progress notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		// Create server with a tool that sends progress notifications
+		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
+				McpSchema.Tool.builder()
+					.name("progress-test")
+					.description("Test progress notifications")
+					.inputSchema(emptyJsonSchema)
+					.build(),
+				null, (exchange, request) -> {
+
+					var progressToken = request.progressToken();
+
+					exchange
+						.progressNotification(
+								new McpSchema.ProgressNotification(progressToken, 0.1, 1.0, "Test progress 1/10"))
+						.block();
+
+					exchange
+						.progressNotification(
+								new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Test progress 5/10"))
+						.block();
+
+					exchange
+						.progressNotification(
+								new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Test progress 10/10"))
+						.block();
+
+					return Mono.just(new CallToolResult("Progress test completed", false));
+				});
+
+		var mcpServer = McpServer.async(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
+			.tools(tool)
+			.build();
+
+		// Create client with progress notification handler
+		try (var mcpClient = clientBuilder.progressConsumer(receivedNotifications::add).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that sends progress notifications
+			CallToolResult result = mcpClient.callTool(
+					new McpSchema.CallToolRequest("progress-test", Map.of(), Map.of("progressToken", "test-token")));
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
+
+			// Wait for notifications to be processed
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				// Should have received 3 notifications
+				assertThat(receivedNotifications).hasSize(3);
+
+				// Check the progress notifications
+				assertThat(receivedNotifications.stream().map(McpSchema.ProgressNotification::progressToken))
+					.containsExactlyInAnyOrder("test-token", "test-token", "test-token");
+				assertThat(receivedNotifications.stream().map(McpSchema.ProgressNotification::progress))
+					.containsExactlyInAnyOrder(0.1, 0.5, 1.0);
+			});
+		}
+		finally {
+			mcpServer.close();
+		}
+	}
+
 	// ---------------------------------------
 	// Ping Tests
 	// ---------------------------------------

From 53f7b77edfa0aef5f45da23ad19632db8c6f9f70 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 17 Jul 2025 13:59:09 +0200
Subject: [PATCH 015/125] refactor: Replace Map with
 CallToolRequest in StructuredOutputCallToolHandler

Follow up to #357 to update tool call handler signature from Map
to McpSchema.CallToolRequest for consistency with changes in #375.

- Change BiFunction parameter from Map to McpSchema.CallToolRequest for better type safety
- Update method signature to accept CallToolRequest instead of raw arguments map
- Replace toolSpecification.call() with toolSpecification.callHandler()
- Migrate to builder pattern for AsyncToolSpecification construction

Signed-off-by: Christian Tzolov 
---
 .../server/McpAsyncServer.java                | 20 ++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index d873a7fde..7131b10fa 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -313,9 +313,9 @@ public Mono addTool(McpServerFeatures.AsyncToolSpecification toolSpecifica
 	}
 
 	private static class StructuredOutputCallToolHandler
-			implements BiFunction, Mono> {
+			implements BiFunction> {
 
-		private final BiFunction, Mono> delegateCallToolResult;
+		private final BiFunction> delegateCallToolResult;
 
 		private final JsonSchemaValidator jsonSchemaValidator;
 
@@ -323,7 +323,7 @@ private static class StructuredOutputCallToolHandler
 
 		public StructuredOutputCallToolHandler(JsonSchemaValidator jsonSchemaValidator,
 				Map outputSchema,
-				BiFunction, Mono> delegateHandler) {
+				BiFunction> delegateHandler) {
 
 			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
 			Assert.notNull(delegateHandler, "Delegate call tool result handler must not be null");
@@ -334,9 +334,9 @@ public StructuredOutputCallToolHandler(JsonSchemaValidator jsonSchemaValidator,
 		}
 
 		@Override
-		public Mono apply(McpAsyncServerExchange exchange, Map arguments) {
+		public Mono apply(McpAsyncServerExchange exchange, McpSchema.CallToolRequest request) {
 
-			return this.delegateCallToolResult.apply(exchange, arguments).map(result -> {
+			return this.delegateCallToolResult.apply(exchange, request).map(result -> {
 
 				if (outputSchema == null) {
 					if (result.structuredContent() != null) {
@@ -398,7 +398,7 @@ private static List withStructuredOutp
 	private static McpServerFeatures.AsyncToolSpecification withStructuredOutputHandling(
 			JsonSchemaValidator jsonSchemaValidator, McpServerFeatures.AsyncToolSpecification toolSpecification) {
 
-		if (toolSpecification.call() instanceof StructuredOutputCallToolHandler) {
+		if (toolSpecification.callHandler() instanceof StructuredOutputCallToolHandler) {
 			// If the tool is already wrapped, return it as is
 			return toolSpecification;
 		}
@@ -408,9 +408,11 @@ private static McpServerFeatures.AsyncToolSpecification withStructuredOutputHand
 			return toolSpecification;
 		}
 
-		return new McpServerFeatures.AsyncToolSpecification(toolSpecification.tool(),
-				new StructuredOutputCallToolHandler(jsonSchemaValidator, toolSpecification.tool().outputSchema(),
-						toolSpecification.call()));
+		return McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(toolSpecification.tool())
+			.callHandler(new StructuredOutputCallToolHandler(jsonSchemaValidator,
+					toolSpecification.tool().outputSchema(), toolSpecification.callHandler()))
+			.build();
 	}
 
 	/**

From 1e93776354be133528ba6e2a8832cc1fa90b5a17 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Wed, 16 Jul 2025 11:06:20 +0200
Subject: [PATCH 016/125] feat: enforce MCP request ID validation requirements

Signed-off-by: Christian Tzolov 
---
 .../modelcontextprotocol/spec/McpSchema.java  | 11 +++
 .../io/modelcontextprotocol/util/Assert.java  | 13 +++
 .../spec/JSONRPCRequestMcpValidationTest.java | 87 +++++++++++++++++++
 3 files changed, 111 insertions(+)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 5ba28cabd..e9c23db6a 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -236,6 +236,17 @@ public record JSONRPCRequest( // @formatter:off
 		@JsonProperty("method") String method,
 		@JsonProperty("id") Object id,
 		@JsonProperty("params") Object params) implements JSONRPCMessage { // @formatter:on
+
+		/**
+		 * Constructor that validates MCP-specific ID requirements. Unlike base JSON-RPC,
+		 * MCP requires that: (1) Requests MUST include a string or integer ID; (2) The ID
+		 * MUST NOT be null
+		 */
+		public JSONRPCRequest {
+			Assert.notNull(id, "MCP requests MUST include an ID - null IDs are not allowed");
+			Assert.isTrue(id instanceof String || id instanceof Integer || id instanceof Long,
+					"MCP requests MUST have an ID that is either a string or integer");
+		}
 	}
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/Assert.java b/mcp/src/main/java/io/modelcontextprotocol/util/Assert.java
index d68188c6f..1fa6b3058 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/util/Assert.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/Assert.java
@@ -76,4 +76,17 @@ public static boolean hasText(@Nullable String str) {
 		return (str != null && !str.isBlank());
 	}
 
+	/**
+	 * Assert a boolean expression, throwing an {@code IllegalArgumentException} if the
+	 * expression evaluates to {@code false}.
+	 * @param expression a boolean expression
+	 * @param message the exception message to use if the assertion fails
+	 * @throws IllegalArgumentException if {@code expression} is {@code false}
+	 */
+	public static void isTrue(boolean expression, String message) {
+		if (!expression) {
+			throw new IllegalArgumentException(message);
+		}
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java b/mcp/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
new file mode 100644
index 000000000..d03a6926d
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
@@ -0,0 +1,87 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.spec;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Tests for MCP-specific validation of JSONRPCRequest ID requirements.
+ *
+ * @author Christian Tzolov
+ */
+public class JSONRPCRequestMcpValidationTest {
+
+	@Test
+	public void testValidStringId() {
+		assertDoesNotThrow(() -> {
+			var request = new McpSchema.JSONRPCRequest("2.0", "test/method", "string-id", null);
+			assertEquals("string-id", request.id());
+		});
+	}
+
+	@Test
+	public void testValidIntegerId() {
+		assertDoesNotThrow(() -> {
+			var request = new McpSchema.JSONRPCRequest("2.0", "test/method", 123, null);
+			assertEquals(123, request.id());
+		});
+	}
+
+	@Test
+	public void testValidLongId() {
+		assertDoesNotThrow(() -> {
+			var request = new McpSchema.JSONRPCRequest("2.0", "test/method", 123L, null);
+			assertEquals(123L, request.id());
+		});
+	}
+
+	@Test
+	public void testNullIdThrowsException() {
+		IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> {
+			new McpSchema.JSONRPCRequest("2.0", "test/method", null, null);
+		});
+
+		assertTrue(exception.getMessage().contains("MCP requests MUST include an ID"));
+		assertTrue(exception.getMessage().contains("null IDs are not allowed"));
+	}
+
+	@Test
+	public void testDoubleIdTypeThrowsException() {
+		IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> {
+			new McpSchema.JSONRPCRequest("2.0", "test/method", 123.45, null);
+		});
+
+		assertTrue(exception.getMessage().contains("MCP requests MUST have an ID that is either a string or integer"));
+	}
+
+	@Test
+	public void testBooleanIdThrowsException() {
+		IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> {
+			new McpSchema.JSONRPCRequest("2.0", "test/method", true, null);
+		});
+
+		assertTrue(exception.getMessage().contains("MCP requests MUST have an ID that is either a string or integer"));
+	}
+
+	@Test
+	public void testArrayIdThrowsException() {
+		IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> {
+			new McpSchema.JSONRPCRequest("2.0", "test/method", new String[] { "array" }, null);
+		});
+
+		assertTrue(exception.getMessage().contains("MCP requests MUST have an ID that is either a string or integer"));
+	}
+
+	@Test
+	public void testObjectIdThrowsException() {
+		IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> {
+			new McpSchema.JSONRPCRequest("2.0", "test/method", new Object(), null);
+		});
+
+		assertTrue(exception.getMessage().contains("MCP requests MUST have an ID that is either a string or integer"));
+	}
+
+}

From 4937fc1ef5317fee4b8febf2c623e1796956bfbf Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Fri, 18 Jul 2025 14:43:35 +0200
Subject: [PATCH 017/125] fix: improve compatibility with non-compliant MCP
 servers (#413)

Addresses issues with servers like Shopify that violate MCP/HTTP specs:
- Prioritize application/json in Accept headers to fix content-type issues
- Handle non-compliant notification non-empty responses
- Add status code validation and null safety improvements

Resolves #406

Signed-off-by: Christian Tzolov 
---
 .../WebClientStreamableHttpTransport.java     | 21 +++++++++++++------
 .../HttpClientStreamableHttpTransport.java    | 14 +++++++++----
 .../client/transport/ResponseSubscribers.java |  9 ++++++++
 .../io/modelcontextprotocol/util/Utils.java   |  3 +++
 4 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 53b59cb30..d5ac8e95c 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -30,6 +30,7 @@
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.spec.McpTransportStream;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.Utils;
 import reactor.core.Disposable;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
@@ -244,7 +245,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 
 			Disposable connection = webClient.post()
 				.uri(this.endpoint)
-				.accept(MediaType.TEXT_EVENT_STREAM, MediaType.APPLICATION_JSON)
+				.accept(MediaType.APPLICATION_JSON, MediaType.TEXT_EVENT_STREAM)
 				.headers(httpHeaders -> {
 					transportSession.sessionId().ifPresent(id -> httpHeaders.add("mcp-session-id", id));
 				})
@@ -287,7 +288,7 @@ else if (mediaType.isCompatibleWith(MediaType.APPLICATION_JSON)) {
 								logger.trace("Received response to POST for session {}", sessionRepresentation);
 								// communicate to caller the message was delivered
 								sink.success();
-								return responseFlux(response);
+								return directResponseFlux(message, response);
 							}
 							else {
 								logger.warn("Unknown media type {} returned for POST in session {}", contentType,
@@ -384,14 +385,22 @@ private static String sessionIdOrPlaceholder(McpTransportSession transportSes
 		return transportSession.sessionId().orElse("[missing_session_id]");
 	}
 
-	private Flux responseFlux(ClientResponse response) {
+	private Flux directResponseFlux(McpSchema.JSONRPCMessage sentMessage,
+			ClientResponse response) {
 		return response.bodyToMono(String.class).>handle((responseMessage, s) -> {
 			try {
-				McpSchema.JSONRPCMessage jsonRpcResponse = McpSchema.deserializeJsonRpcMessage(objectMapper,
-						responseMessage);
-				s.next(List.of(jsonRpcResponse));
+				if (sentMessage instanceof McpSchema.JSONRPCNotification && Utils.hasText(responseMessage)) {
+					logger.warn("Notification: {} received non-compliant response: {}", sentMessage, responseMessage);
+					s.complete();
+				}
+				else {
+					McpSchema.JSONRPCMessage jsonRpcResponse = McpSchema.deserializeJsonRpcMessage(objectMapper,
+							responseMessage);
+					s.next(List.of(jsonRpcResponse));
+				}
 			}
 			catch (IOException e) {
+				// TODO: this should be a McpTransportError
 				s.error(e);
 			}
 		}).flatMapIterable(Function.identity());
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index 4cf1690ff..12baa1706 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -342,9 +342,9 @@ public String toString(McpSchema.JSONRPCMessage message) {
 		}
 	}
 
-	public Mono sendMessage(McpSchema.JSONRPCMessage sendMessage) {
+	public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 		return Mono.create(messageSink -> {
-			logger.debug("Sending message {}", sendMessage);
+			logger.debug("Sending message {}", sentMessage);
 
 			final AtomicReference disposableRef = new AtomicReference<>();
 			final McpTransportSession transportSession = this.activeSession.get();
@@ -355,10 +355,10 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sendMessage) {
 				requestBuilder = requestBuilder.header("mcp-session-id", transportSession.sessionId().get());
 			}
 
-			String jsonBody = this.toString(sendMessage);
+			String jsonBody = this.toString(sentMessage);
 
 			HttpRequest request = requestBuilder.uri(Utils.resolveUri(this.baseUri, this.endpoint))
-				.header("Accept", TEXT_EVENT_STREAM + ", " + APPLICATION_JSON)
+				.header("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
 				.header("Content-Type", APPLICATION_JSON)
 				.header("Cache-Control", "no-cache")
 				.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
@@ -436,10 +436,16 @@ else if (contentType.contains(TEXT_EVENT_STREAM)) {
 					else if (contentType.contains(APPLICATION_JSON)) {
 						messageSink.success();
 						String data = ((ResponseSubscribers.AggregateResponseEvent) responseEvent).data();
+						if (sentMessage instanceof McpSchema.JSONRPCNotification && Utils.hasText(data)) {
+							logger.warn("Notification: {} received non-compliant response: {}", sentMessage, data);
+							return Mono.empty();
+						}
+
 						try {
 							return Mono.just(McpSchema.deserializeJsonRpcMessage(objectMapper, data));
 						}
 						catch (IOException e) {
+							// TODO: this should be a McpTransportError
 							return Mono.error(e);
 						}
 					}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
index 26b0d13bd..eb9d3c65c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
@@ -12,6 +12,7 @@
 import org.reactivestreams.FlowAdapters;
 import org.reactivestreams.Subscription;
 
+import io.modelcontextprotocol.spec.McpError;
 import reactor.core.publisher.BaseSubscriber;
 import reactor.core.publisher.FluxSink;
 
@@ -135,6 +136,7 @@ protected void hookOnSubscribe(Subscription subscription) {
 
 		@Override
 		protected void hookOnNext(String line) {
+
 			if (line.isEmpty()) {
 				// Empty line means end of event
 				if (this.eventBuilder.length() > 0) {
@@ -164,6 +166,13 @@ else if (line.startsWith("event:")) {
 						this.currentEventType.set(matcher.group(1).trim());
 					}
 				}
+				else {
+					// If the response is not successful, emit an error
+					// TODO: This should be a McpTransportError
+					this.sink.error(new McpError(
+							"Invalid SSE response. Status code: " + this.responseInfo.statusCode() + " Line: " + line));
+
+				}
 			}
 		}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java b/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java
index 8e654e596..039b0d68e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java
@@ -69,6 +69,9 @@ public static boolean isEmpty(@Nullable Map map) {
 	 * base URL or URI is malformed
 	 */
 	public static URI resolveUri(URI baseUrl, String endpointUrl) {
+		if (!Utils.hasText(endpointUrl)) {
+			return baseUrl;
+		}
 		URI endpointUri = URI.create(endpointUrl);
 		if (endpointUri.isAbsolute() && !isUnderBaseUri(baseUrl, endpointUri)) {
 			throw new IllegalArgumentException("Absolute endpoint URL does not match the base URL.");

From c3a0b1855ab2ac18a2b6120773ac4e5060285d8b Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 24 Jul 2025 15:48:01 +0200
Subject: [PATCH 018/125] fix: improve SSE event handling to gracefully ignore
 unrecognized events (#423)

- Replace McpError exceptions with debug/warning logs for unrecognized SSE event types
- Continue processing instead of failing when encountering unknown SSE events
- Update transport implementations:
  - WebClientStreamableHttpTransport: return empty tuple instead of throwing
  - WebFluxSseClientTransport: complete stream instead of erroring
  - HttpClientSseClientTransport: call sink.success() instead of sink.error()
  - HttpClientStreamableHttpTransport: return empty Flux for unknown events

This improves client resilience when servers send non-standard or future SSE event types.

Resolves #272 , #223 , #93, #421

Signed-off-by: Christian Tzolov 
---
 .../WebClientStreamableHttpTransport.java     |  3 ++-
 .../transport/WebFluxSseClientTransport.java  |  3 ++-
 .../WebFluxSseClientTransportTests.java       | 27 +++++++++++++++++++
 .../HttpClientSseClientTransport.java         |  6 ++---
 .../HttpClientStreamableHttpTransport.java    |  4 +++
 5 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index d5ac8e95c..abe6d33eb 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -432,7 +432,8 @@ private Tuple2, Iterable> parse(Serve
 			}
 		}
 		else {
-			throw new McpError("Received unrecognized SSE event type: " + event.event());
+			logger.debug("Received SSE event with type: {}", event);
+			return Tuples.of(Optional.empty(), List.of());
 		}
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
index 128cda4c3..59385b54a 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
@@ -216,7 +216,8 @@ else if (MESSAGE_EVENT_TYPE.equals(event.event())) {
 				}
 			}
 			else {
-				s.error(new McpError("Received unrecognized SSE event type: " + event.event()));
+				logger.debug("Received unrecognized SSE event type: {}", event);
+				s.complete();
 			}
 		}).transform(handler)).subscribe();
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
index 42b91d14e..1cf5dffe2 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
@@ -6,6 +6,7 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.function.Function;
 
@@ -77,6 +78,11 @@ public int getInboundMessageCount() {
 			return inboundMessageCount.get();
 		}
 
+		public void simulateSseComment(String comment) {
+			events.tryEmitNext(ServerSentEvent.builder().comment(comment).build());
+			inboundMessageCount.incrementAndGet();
+		}
+
 		public void simulateEndpointEvent(String jsonMessage) {
 			events.tryEmitNext(ServerSentEvent.builder().event("endpoint").data(jsonMessage).build());
 			inboundMessageCount.incrementAndGet();
@@ -158,6 +164,27 @@ void testBuilderPattern() {
 		assertThatCode(() -> transport4.closeGracefully().block()).doesNotThrowAnyException();
 	}
 
+	@Test
+	void testCommentSseMessage() {
+		// If the line starts with a character (:) are comment lins and should be ingored
+		// https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation
+
+		CopyOnWriteArrayList droppedErrors = new CopyOnWriteArrayList<>();
+		reactor.core.publisher.Hooks.onErrorDropped(droppedErrors::add);
+
+		try {
+			// Simulate receiving the SSE comment line
+			transport.simulateSseComment("sse comment");
+
+			StepVerifier.create(transport.closeGracefully()).verifyComplete();
+
+			assertThat(droppedErrors).hasSize(0);
+		}
+		finally {
+			reactor.core.publisher.Hooks.resetOnErrorDropped();
+		}
+	}
+
 	@Test
 	void testMessageProcessing() {
 		// Create a test message
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 8598e3164..b610ad93a 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -366,10 +366,8 @@ else if (MESSAGE_EVENT_TYPE.equals(responseEvent.sseEvent().event())) {
 								return Flux.just(message);
 							}
 							else {
-								logger.error("Received unrecognized SSE event type: {}",
-										responseEvent.sseEvent().event());
-								sink.error(new McpError(
-										"Received unrecognized SSE event type: " + responseEvent.sseEvent().event()));
+								logger.debug("Received unrecognized SSE event type: {}", responseEvent.sseEvent());
+								sink.success();
 							}
 						}
 						catch (IOException e) {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index 12baa1706..d8dd97f1e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -264,6 +264,10 @@ private Mono reconnect(McpTransportStream stream) {
 										"Error parsing JSON-RPC message: " + responseEvent.sseEvent().data()));
 							}
 						}
+						else {
+							logger.debug("Received SSE event with type: {}", responseEvent.sseEvent());
+							return Flux.empty();
+						}
 					}
 					else if (statusCode == METHOD_NOT_ALLOWED) { // NotAllowed
 						logger.debug("The server does not support SSE streams, using request-response mode.");

From a8f5a3fb4f958bdecf5160495fc6f47089b93c88 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dariusz=20J=C4=99drzejczyk?=
 
Date: Wed, 30 Jul 2025 13:41:18 +0200
Subject: [PATCH 019/125] feat: add Streamable HTTP Server abstractions and
 implement WebFlux transport provider (#420)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add WebFluxStreamableServerTransportProvider for streamable HTTP sessions
- Add WebFluxStatelessServerTransport for stateless HTTP MCP servers
  - Add McpStatelessServerFeatures, McpStatelessServerHandler, McpStatelessRequestHandler, McpStatelessNotificationHandler
- Refactor server architecture to support multiple transport categories:
   streamable, single-session, stateless
- Introduce McpTransportContext for transport-level metadata extraction
- Add session management capabilities for streamable HTTP connections
- Update MCP protocol version to 2025-03-26
- Add test coverage for new transport implementations
- Implement integration tests for both stateless and streamable transports

Signed-off-by: Dariusz Jędrzejczyk 
Signed-off-by: Christian Tzolov 
Co-authored-by: Christian Tzolov 
---
 .../WebClientStreamableHttpTransport.java     |    3 +-
 .../WebFluxStatelessServerTransport.java      |  213 +++
 ...FluxStreamableServerTransportProvider.java |  443 +++++
 .../WebFluxStatelessIntegrationTests.java     |  472 ++++++
 .../WebFluxStreamableIntegrationTests.java    | 1492 +++++++++++++++++
 .../server/WebFluxSseMcpAsyncServerTests.java |    8 +-
 .../server/WebFluxSseMcpSyncServerTests.java  |    6 +-
 .../WebFluxStreamableMcpAsyncServerTests.java |   63 +
 .../WebFluxStreamableMcpSyncServerTests.java  |   62 +
 .../WebMvcSseAsyncServerTransportTests.java   |    8 +-
 .../WebMvcSseSyncServerTransportTests.java    |    6 +-
 .../server/AbstractMcpAsyncServerTests.java   |   97 +-
 .../server/AbstractMcpSyncServerTests.java    |   89 +-
 .../DefaultMcpStatelessServerHandler.java     |   50 +
 .../server/DefaultMcpTransportContext.java    |   45 +
 .../server/McpAsyncServer.java                |   96 +-
 .../server/McpAsyncServerExchange.java        |   64 +-
 .../server/McpInitRequestHandler.java         |   18 +
 .../server/McpNotificationHandler.java        |   19 +
 .../server/McpRequestHandler.java             |   22 +
 .../server/McpServer.java                     | 1326 +++++++++++++--
 .../server/McpStatelessAsyncServer.java       |  671 ++++++++
 .../McpStatelessNotificationHandler.java      |   20 +
 .../server/McpStatelessRequestHandler.java    |   21 +
 .../server/McpStatelessServerFeatures.java    |  379 +++++
 .../server/McpStatelessServerHandler.java     |   33 +
 .../server/McpStatelessSyncServer.java        |  132 ++
 .../server/McpSyncServerExchange.java         |   18 +
 .../server/McpTransportContext.java           |   46 +
 .../server/McpTransportContextExtractor.java  |   24 +
 ...aultMcpStreamableServerSessionFactory.java |   52 +
 .../spec/HttpHeaders.java                     |   20 +
 .../spec/McpLoggableSession.java              |   25 +
 .../modelcontextprotocol/spec/McpSchema.java  |    2 +-
 .../spec/McpServerSession.java                |   74 +-
 .../spec/McpServerTransportProvider.java      |   53 +-
 .../spec/McpServerTransportProviderBase.java  |   58 +
 .../modelcontextprotocol/spec/McpSession.java |    1 +
 .../spec/McpStatelessServerTransport.java     |   25 +
 .../spec/McpStreamableServerSession.java      |  398 +++++
 .../spec/McpStreamableServerTransport.java    |   20 +
 .../McpStreamableServerTransportProvider.java |   67 +
 .../spec/MissingMcpTransportSession.java      |   59 +
 .../client/StdioMcpAsyncClientTests.java      |    2 +-
 .../server/AbstractMcpAsyncServerTests.java   |   97 +-
 .../server/AbstractMcpSyncServerTests.java    |   89 +-
 .../server/McpAsyncServerExchangeTests.java   |  142 +-
 .../server/McpCompletionTests.java            |    6 +-
 .../server/McpSyncServerExchangeTests.java    |  122 +-
 .../server/ServletSseMcpAsyncServerTests.java |    6 +-
 .../server/ServletSseMcpSyncServerTests.java  |    6 +-
 .../server/StdioMcpAsyncServerTests.java      |    6 +-
 .../server/StdioMcpSyncServerTests.java       |    6 +-
 53 files changed, 6578 insertions(+), 704 deletions(-)
 create mode 100644 mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index abe6d33eb..6fa76cc2e 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -341,7 +341,8 @@ private Flux extractError(ClientResponse response, Str
 				McpSchema.JSONRPCResponse jsonRpcResponse = objectMapper.readValue(body,
 						McpSchema.JSONRPCResponse.class);
 				jsonRpcError = jsonRpcResponse.error();
-				toPropagate = new McpError(jsonRpcError);
+				toPropagate = jsonRpcError != null ? new McpError(jsonRpcError)
+						: new McpError("Can't parse the jsonResponse " + jsonRpcResponse);
 			}
 			catch (IOException ex) {
 				toPropagate = new RuntimeException("Sending request failed", e);
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
new file mode 100644
index 000000000..e75e9262d
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
@@ -0,0 +1,213 @@
+package io.modelcontextprotocol.server.transport;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.McpStatelessServerHandler;
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpStatelessServerTransport;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.util.Assert;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.web.reactive.function.server.RouterFunction;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import org.springframework.web.reactive.function.server.ServerRequest;
+import org.springframework.web.reactive.function.server.ServerResponse;
+import reactor.core.publisher.Mono;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.function.Function;
+
+/**
+ * Implementation of a WebFlux based {@link McpStatelessServerTransport}.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class WebFluxStatelessServerTransport implements McpStatelessServerTransport {
+
+	private static final Logger logger = LoggerFactory.getLogger(WebFluxStatelessServerTransport.class);
+
+	private final ObjectMapper objectMapper;
+
+	private final String mcpEndpoint;
+
+	private final RouterFunction routerFunction;
+
+	private McpStatelessServerHandler mcpHandler;
+
+	private McpTransportContextExtractor contextExtractor;
+
+	private volatile boolean isClosing = false;
+
+	private WebFluxStatelessServerTransport(ObjectMapper objectMapper, String mcpEndpoint,
+			McpTransportContextExtractor contextExtractor) {
+		Assert.notNull(objectMapper, "objectMapper must not be null");
+		Assert.notNull(mcpEndpoint, "mcpEndpoint must not be null");
+		Assert.notNull(contextExtractor, "contextExtractor must not be null");
+
+		this.objectMapper = objectMapper;
+		this.mcpEndpoint = mcpEndpoint;
+		this.contextExtractor = contextExtractor;
+		this.routerFunction = RouterFunctions.route()
+			.GET(this.mcpEndpoint, this::handleGet)
+			.POST(this.mcpEndpoint, this::handlePost)
+			.build();
+	}
+
+	@Override
+	public void setMcpHandler(McpStatelessServerHandler mcpHandler) {
+		this.mcpHandler = mcpHandler;
+	}
+
+	@Override
+	public Mono closeGracefully() {
+		return Mono.fromRunnable(() -> this.isClosing = true);
+	}
+
+	/**
+	 * Returns the WebFlux router function that defines the transport's HTTP endpoints.
+	 * This router function should be integrated into the application's web configuration.
+	 *
+	 * 

+	 * The router function defines one endpoint handling two HTTP methods:
+	 * 
    
+	 * 
  • GET {messageEndpoint} - Unsupported, returns 405 METHOD NOT ALLOWED
    • 
+	 * 
  • POST {messageEndpoint} - For handling client requests and notifications
    • 
+	 * 

+	 * @return The configured {@link RouterFunction} for handling HTTP requests
+	 */
+	public RouterFunction getRouterFunction() {
+		return this.routerFunction;
+	}
+
+	private Mono handleGet(ServerRequest request) {
+		return ServerResponse.status(HttpStatus.METHOD_NOT_ALLOWED).build();
+	}
+
+	private Mono handlePost(ServerRequest request) {
+		if (isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
+		if (!(acceptHeaders.contains(MediaType.APPLICATION_JSON)
+				&& acceptHeaders.contains(MediaType.TEXT_EVENT_STREAM))) {
+			return ServerResponse.badRequest().build();
+		}
+
+		return request.bodyToMono(String.class).flatMap(body -> {
+			try {
+				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+
+				if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
+					return this.mcpHandler.handleRequest(transportContext, jsonrpcRequest)
+						.flatMap(jsonrpcResponse -> ServerResponse.ok()
+							.contentType(MediaType.APPLICATION_JSON)
+							.bodyValue(jsonrpcResponse));
+				}
+				else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
+					return this.mcpHandler.handleNotification(transportContext, jsonrpcNotification)
+						.then(ServerResponse.accepted().build());
+				}
+				else {
+					return ServerResponse.badRequest()
+						.bodyValue(new McpError("The server accepts either requests or notifications"));
+				}
+			}
+			catch (IllegalArgumentException | IOException e) {
+				logger.error("Failed to deserialize message: {}", e.getMessage());
+				return ServerResponse.badRequest().bodyValue(new McpError("Invalid message format"));
+			}
+		}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext));
+	}
+
+	/**
+	 * Create a builder for the server.
+	 * @return a fresh {@link Builder} instance.
+	 */
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for creating instances of {@link WebFluxStatelessServerTransport}.
+	 * 

+	 * This builder provides a fluent API for configuring and creating instances of
+	 * WebFluxSseServerTransportProvider with custom settings.
+	 */
+	public static class Builder {
+
+		private ObjectMapper objectMapper;
+
+		private String mcpEndpoint = "/mcp";
+
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
+		private Builder() {
+			// used by a static method
+		}
+
+		/**
+		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * messages.
+		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public Builder objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint URI where clients should send their JSON-RPC messages.
+		 * @param messageEndpoint The message endpoint URI. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if messageEndpoint is null
+		 */
+		public Builder messageEndpoint(String messageEndpoint) {
+			Assert.notNull(messageEndpoint, "Message endpoint must not be null");
+			this.mcpEndpoint = messageEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets the context extractor that allows providing the MCP feature
+		 * implementations to inspect HTTP transport level metadata that was present at
+		 * HTTP request processing time. This allows to extract custom headers and other
+		 * useful data for use during execution later on in the process.
+		 * @param contextExtractor The contextExtractor to fill in a
+		 * {@link McpTransportContext}.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "Context extractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
+		/**
+		 * Builds a new instance of {@link WebFluxStatelessServerTransport} with the
+		 * configured settings.
+		 * @return A new WebFluxSseServerTransportProvider instance
+		 * @throws IllegalStateException if required parameters are not set
+		 */
+		public WebFluxStatelessServerTransport build() {
+			Assert.notNull(objectMapper, "ObjectMapper must be set");
+			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
+
+			return new WebFluxStatelessServerTransport(objectMapper, mcpEndpoint, contextExtractor);
+		}
+
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
new file mode 100644
index 000000000..750828adb
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -0,0 +1,443 @@
+package io.modelcontextprotocol.server.transport;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.spec.HttpHeaders;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpStreamableServerSession;
+import io.modelcontextprotocol.spec.McpStreamableServerTransport;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.util.Assert;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.codec.ServerSentEvent;
+import org.springframework.web.reactive.function.server.RouterFunction;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import org.springframework.web.reactive.function.server.ServerRequest;
+import org.springframework.web.reactive.function.server.ServerResponse;
+import reactor.core.Disposable;
+import reactor.core.Exceptions;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.FluxSink;
+import reactor.core.publisher.Mono;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Implementation of a WebFlux based {@link McpStreamableServerTransportProvider}.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class WebFluxStreamableServerTransportProvider implements McpStreamableServerTransportProvider {
+
+	private static final Logger logger = LoggerFactory.getLogger(WebFluxStreamableServerTransportProvider.class);
+
+	public static final String MESSAGE_EVENT_TYPE = "message";
+
+	private final ObjectMapper objectMapper;
+
+	private final String mcpEndpoint;
+
+	private final boolean disallowDelete;
+
+	private final RouterFunction routerFunction;
+
+	private McpStreamableServerSession.Factory sessionFactory;
+
+	private final ConcurrentHashMap sessions = new ConcurrentHashMap<>();
+
+	private McpTransportContextExtractor contextExtractor;
+
+	private volatile boolean isClosing = false;
+
+	private WebFluxStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
+			McpTransportContextExtractor contextExtractor, boolean disallowDelete) {
+		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(mcpEndpoint, "Message endpoint must not be null");
+		Assert.notNull(contextExtractor, "Context extractor must not be null");
+
+		this.objectMapper = objectMapper;
+		this.mcpEndpoint = mcpEndpoint;
+		this.contextExtractor = contextExtractor;
+		this.disallowDelete = disallowDelete;
+		this.routerFunction = RouterFunctions.route()
+			.GET(this.mcpEndpoint, this::handleGet)
+			.POST(this.mcpEndpoint, this::handlePost)
+			.DELETE(this.mcpEndpoint, this::handleDelete)
+			.build();
+	}
+
+	@Override
+	public void setSessionFactory(McpStreamableServerSession.Factory sessionFactory) {
+		this.sessionFactory = sessionFactory;
+	}
+
+	@Override
+	public Mono notifyClients(String method, Object params) {
+		if (sessions.isEmpty()) {
+			logger.debug("No active sessions to broadcast message to");
+			return Mono.empty();
+		}
+
+		logger.debug("Attempting to broadcast message to {} active sessions", sessions.size());
+
+		return Flux.fromIterable(sessions.values())
+			.flatMap(session -> session.sendNotification(method, params)
+				.doOnError(
+						e -> logger.error("Failed to send message to session {}: {}", session.getId(), e.getMessage()))
+				.onErrorComplete())
+			.then();
+	}
+
+	@Override
+	public Mono closeGracefully() {
+		return Mono.defer(() -> {
+			this.isClosing = true;
+			return Flux.fromIterable(sessions.values())
+				.doFirst(() -> logger.debug("Initiating graceful shutdown with {} active sessions", sessions.size()))
+				.flatMap(McpStreamableServerSession::closeGracefully)
+				.then();
+		});
+	}
+
+	/**
+	 * Returns the WebFlux router function that defines the transport's HTTP endpoints.
+	 * This router function should be integrated into the application's web configuration.
+	 *
+	 * 

+	 * The router function defines one endpoint with three methods:
+	 * 
    
+	 * 
  • GET {messageEndpoint} - For the client listening SSE stream
    • 
+	 * 
  • POST {messageEndpoint} - For receiving client messages
    • 
+	 * 
  • DELETE {messageEndpoint} - For removing sessions
    • 
+	 * 

+	 * @return The configured {@link RouterFunction} for handling HTTP requests
+	 */
+	public RouterFunction getRouterFunction() {
+		return this.routerFunction;
+	}
+
+	/**
+	 * Opens the listening SSE streams for clients.
+	 * @param request The incoming server request
+	 * @return A Mono which emits a response with the SSE event stream
+	 */
+	private Mono handleGet(ServerRequest request) {
+		if (isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		return Mono.defer(() -> {
+			List acceptHeaders = request.headers().asHttpHeaders().getAccept();
+			if (!acceptHeaders.contains(MediaType.TEXT_EVENT_STREAM)) {
+				return ServerResponse.badRequest().build();
+			}
+
+			if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+				return ServerResponse.badRequest().build(); // TODO: say we need a session
+															// id
+			}
+
+			String sessionId = request.headers().asHttpHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+
+			McpStreamableServerSession session = this.sessions.get(sessionId);
+
+			if (session == null) {
+				return ServerResponse.notFound().build();
+			}
+
+			if (request.headers().asHttpHeaders().containsKey(HttpHeaders.LAST_EVENT_ID)) {
+				String lastId = request.headers().asHttpHeaders().getFirst(HttpHeaders.LAST_EVENT_ID);
+				return ServerResponse.ok()
+					.contentType(MediaType.TEXT_EVENT_STREAM)
+					.body(session.replay(lastId), ServerSentEvent.class);
+			}
+
+			return ServerResponse.ok()
+				.contentType(MediaType.TEXT_EVENT_STREAM)
+				.body(Flux.>create(sink -> {
+					WebFluxStreamableMcpSessionTransport sessionTransport = new WebFluxStreamableMcpSessionTransport(
+							sink);
+					McpStreamableServerSession.McpStreamableServerSessionStream listeningStream = session
+						.listeningStream(sessionTransport);
+					sink.onDispose(listeningStream::close);
+				}), ServerSentEvent.class);
+
+		}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext));
+	}
+
+	/**
+	 * Handles incoming JSON-RPC messages from clients.
+	 * @param request The incoming server request containing the JSON-RPC message
+	 * @return A Mono with the response appropriate to a particular Streamable HTTP flow.
+	 */
+	private Mono handlePost(ServerRequest request) {
+		if (isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
+		if (!(acceptHeaders.contains(MediaType.APPLICATION_JSON)
+				&& acceptHeaders.contains(MediaType.TEXT_EVENT_STREAM))) {
+			return ServerResponse.badRequest().build();
+		}
+
+		return request.bodyToMono(String.class).flatMap(body -> {
+			try {
+				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+				if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest
+						&& jsonrpcRequest.method().equals(McpSchema.METHOD_INITIALIZE)) {
+					McpSchema.InitializeRequest initializeRequest = objectMapper.convertValue(jsonrpcRequest.params(),
+							new TypeReference() {
+							});
+					McpStreamableServerSession.McpStreamableServerSessionInit init = this.sessionFactory
+						.startSession(initializeRequest);
+					sessions.put(init.session().getId(), init.session());
+					return init.initResult().map(initializeResult -> {
+						McpSchema.JSONRPCResponse jsonrpcResponse = new McpSchema.JSONRPCResponse(
+								McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), initializeResult, null);
+						try {
+							return this.objectMapper.writeValueAsString(jsonrpcResponse);
+						}
+						catch (IOException e) {
+							logger.warn("Failed to serialize initResponse", e);
+							throw Exceptions.propagate(e);
+						}
+					})
+						.flatMap(initResult -> ServerResponse.ok()
+							.contentType(MediaType.APPLICATION_JSON)
+							.header(HttpHeaders.MCP_SESSION_ID, init.session().getId())
+							.bodyValue(initResult));
+				}
+
+				if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+					return ServerResponse.badRequest().bodyValue(new McpError("Session ID missing"));
+				}
+
+				String sessionId = request.headers().asHttpHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+				McpStreamableServerSession session = sessions.get(sessionId);
+
+				if (session == null) {
+					return ServerResponse.status(HttpStatus.NOT_FOUND)
+						.bodyValue(new McpError("Session not found: " + sessionId));
+				}
+
+				if (message instanceof McpSchema.JSONRPCResponse jsonrpcResponse) {
+					return session.accept(jsonrpcResponse).then(ServerResponse.accepted().build());
+				}
+				else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
+					return session.accept(jsonrpcNotification).then(ServerResponse.accepted().build());
+				}
+				else if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
+					return ServerResponse.ok()
+						.contentType(MediaType.TEXT_EVENT_STREAM)
+						.body(Flux.>create(sink -> {
+							WebFluxStreamableMcpSessionTransport st = new WebFluxStreamableMcpSessionTransport(sink);
+							Mono stream = session.responseStream(jsonrpcRequest, st);
+							Disposable streamSubscription = stream.onErrorComplete(err -> {
+								sink.error(err);
+								return true;
+							}).contextWrite(sink.contextView()).subscribe();
+							sink.onCancel(streamSubscription);
+						}), ServerSentEvent.class);
+				}
+				else {
+					return ServerResponse.badRequest().bodyValue(new McpError("Unknown message type"));
+				}
+			}
+			catch (IllegalArgumentException | IOException e) {
+				logger.error("Failed to deserialize message: {}", e.getMessage());
+				return ServerResponse.badRequest().bodyValue(new McpError("Invalid message format"));
+			}
+		})
+			.switchIfEmpty(ServerResponse.badRequest().build())
+			.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext));
+	}
+
+	private Mono handleDelete(ServerRequest request) {
+		if (isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		return Mono.defer(() -> {
+			if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+				return ServerResponse.badRequest().build(); // TODO: say we need a session
+															// id
+			}
+
+			if (this.disallowDelete) {
+				return ServerResponse.status(HttpStatus.METHOD_NOT_ALLOWED).build();
+			}
+
+			String sessionId = request.headers().asHttpHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+
+			McpStreamableServerSession session = this.sessions.get(sessionId);
+
+			if (session == null) {
+				return ServerResponse.notFound().build();
+			}
+
+			return session.delete().then(ServerResponse.ok().build());
+		}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext));
+	}
+
+	private class WebFluxStreamableMcpSessionTransport implements McpStreamableServerTransport {
+
+		private final FluxSink> sink;
+
+		public WebFluxStreamableMcpSessionTransport(FluxSink> sink) {
+			this.sink = sink;
+		}
+
+		@Override
+		public Mono sendMessage(McpSchema.JSONRPCMessage message) {
+			return this.sendMessage(message, null);
+		}
+
+		@Override
+		public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId) {
+			return Mono.fromSupplier(() -> {
+				try {
+					return objectMapper.writeValueAsString(message);
+				}
+				catch (IOException e) {
+					throw Exceptions.propagate(e);
+				}
+			}).doOnNext(jsonText -> {
+				ServerSentEvent event = ServerSentEvent.builder()
+					.id(messageId)
+					.event(MESSAGE_EVENT_TYPE)
+					.data(jsonText)
+					.build();
+				sink.next(event);
+			}).doOnError(e -> {
+				// TODO log with sessionid
+				Throwable exception = Exceptions.unwrap(e);
+				sink.error(exception);
+			}).then();
+		}
+
+		@Override
+		public  T unmarshalFrom(Object data, TypeReference typeRef) {
+			return objectMapper.convertValue(data, typeRef);
+		}
+
+		@Override
+		public Mono closeGracefully() {
+			return Mono.fromRunnable(sink::complete);
+		}
+
+		@Override
+		public void close() {
+			sink.complete();
+		}
+
+	}
+
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for creating instances of {@link WebFluxStreamableServerTransportProvider}.
+	 * 

+	 * This builder provides a fluent API for configuring and creating instances of
+	 * WebFluxStreamableServerTransportProvider with custom settings.
+	 */
+	public static class Builder {
+
+		private ObjectMapper objectMapper;
+
+		private String mcpEndpoint = "/mcp";
+
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
+		private boolean disallowDelete;
+
+		private Builder() {
+			// used by a static method
+		}
+
+		/**
+		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * messages.
+		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public Builder objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint URI where clients should send their JSON-RPC messages.
+		 * @param messageEndpoint The message endpoint URI. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if messageEndpoint is null
+		 */
+		public Builder messageEndpoint(String messageEndpoint) {
+			Assert.notNull(messageEndpoint, "Message endpoint must not be null");
+			this.mcpEndpoint = messageEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets the context extractor that allows providing the MCP feature
+		 * implementations to inspect HTTP transport level metadata that was present at
+		 * HTTP request processing time. This allows to extract custom headers and other
+		 * useful data for use during execution later on in the process.
+		 * @param contextExtractor The contextExtractor to fill in a
+		 * {@link McpTransportContext}.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "contextExtractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
+		/**
+		 * Sets whether the session removal capability is disabled.
+		 * @param disallowDelete if {@code true}, the DELETE endpoint will not be
+		 * supported and sessions won't be deleted.
+		 * @return this builder instance
+		 */
+		public Builder disallowDelete(boolean disallowDelete) {
+			this.disallowDelete = disallowDelete;
+			return this;
+		}
+
+		/**
+		 * Builds a new instance of {@link WebFluxStreamableServerTransportProvider} with
+		 * the configured settings.
+		 * @return A new WebFluxStreamableServerTransportProvider instance
+		 * @throws IllegalStateException if required parameters are not set
+		 */
+		public WebFluxStreamableServerTransportProvider build() {
+			Assert.notNull(objectMapper, "ObjectMapper must be set");
+			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
+
+			return new WebFluxStreamableServerTransportProvider(objectMapper, mcpEndpoint, contextExtractor,
+					disallowDelete);
+		}
+
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
new file mode 100644
index 000000000..2f1765df7
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
@@ -0,0 +1,472 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.transport.WebFluxStatelessServerTransport;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.Prompt;
+import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import io.modelcontextprotocol.server.McpTransportContext;
+import net.javacrumbs.jsonunit.core.Option;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
+
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
+
+class WebFluxStatelessIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String CUSTOM_MESSAGE_ENDPOINT = "/otherPath/mcp/message";
+
+	private DisposableServer httpServer;
+
+	private WebFluxStatelessServerTransport mcpStreamableServerTransport;
+
+	ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
+
+	@BeforeEach
+	public void before() {
+		this.mcpStreamableServerTransport = WebFluxStatelessServerTransport.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
+			.build();
+
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(mcpStreamableServerTransport.getRouterFunction());
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+						.endpoint(CUSTOM_MESSAGE_ENDPOINT)
+						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
+		clientBuilders
+			.put("webflux", McpClient
+				.sync(WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
+					.endpoint(CUSTOM_MESSAGE_ENDPOINT)
+					.build())
+				.initializationTimeout(Duration.ofHours(10))
+				.requestTimeout(Duration.ofHours(10)));
+
+	}
+
+	@AfterEach
+	public void after() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+	// ---------------------------------------
+	// Tools Tests
+	// ---------------------------------------
+
+	String emptyJsonSchema = """
+			{
+			"$schema": "http://json-schema.org/draft-07/schema#",
+			"type": "object",
+			"properties": {}
+			}
+			""";
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolCallSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpStatelessServerFeatures.SyncToolSpecification tool1 = new McpStatelessServerFeatures.SyncToolSpecification(
+				new Tool("tool1", "tool1 description", emptyJsonSchema), (transportContext, request) -> {
+					// perform a blocking call to a remote service
+					String response = RestClient.create()
+						.get()
+						.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
+						.retrieve()
+						.body(String.class);
+					assertThat(response).isNotBlank();
+					return callResponse;
+				});
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testInitialize(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransport).build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Completion Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : Completion call")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var expectedValues = List.of("python", "pytorch", "pyside");
+		var completionResponse = new CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
+				true // hasMore
+		));
+
+		AtomicReference samplingRequest = new AtomicReference<>();
+		BiFunction completionHandler = (transportContext,
+				request) -> {
+			samplingRequest.set(request);
+			return completionResponse;
+		};
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
+			.capabilities(ServerCapabilities.builder().completions().build())
+			.prompts(new McpStatelessServerFeatures.SyncPromptSpecification(
+					new Prompt("code_review", "Code review", "this is code review prompt",
+							List.of(new PromptArgument("language", "Language", "string", false))),
+					(transportContext, getPromptRequest) -> null))
+			.completions(new McpStatelessServerFeatures.SyncCompletionSpecification(
+					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CompleteRequest request = new CompleteRequest(
+					new PromptReference("ref/prompt", "code_review", "Code review"),
+					new CompleteRequest.CompleteArgument("language", "py"));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			assertThat(result).isNotNull();
+
+			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
+			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
+				calculatorTool, (transportContext, request) -> {
+					String expression = (String) request.arguments().getOrDefault("expression", "2 + 3");
+					double result = evaluateExpression(expression);
+					return CallToolResult.builder()
+						.structuredContent(
+								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationFailure(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
+				calculatorTool, (transportContext, request) -> {
+					// Return invalid structured output. Result should be number, missing
+					// operation
+					return CallToolResult.builder()
+						.addTextContent("Invalid calculation")
+						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputMissingStructuredContent(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
+				calculatorTool, (transportContext, request) -> {
+					// Return result without structured content but tool has output schema
+					return CallToolResult.builder().addTextContent("Calculation completed").build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.instructions("bla")
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputRuntimeToolAddition(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Start server without tools
+		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpStatelessServerFeatures.SyncToolSpecification toolSpec = new McpStatelessServerFeatures.SyncToolSpecification(
+					dynamicTool, (transportContext, request) -> {
+						int count = (Integer) request.arguments().getOrDefault("count", 1);
+						return CallToolResult.builder()
+							.addTextContent("Dynamic tool executed " + count + " times")
+							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+							.build();
+					});
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
new file mode 100644
index 000000000..bc13ad9c6
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -0,0 +1,1492 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
+import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
+import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
+import io.modelcontextprotocol.spec.McpSchema.Prompt;
+import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
+import io.modelcontextprotocol.spec.McpSchema.Role;
+import io.modelcontextprotocol.spec.McpSchema.Root;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import net.javacrumbs.jsonunit.core.Option;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import reactor.core.publisher.Mono;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+import reactor.test.StepVerifier;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertWith;
+import static org.awaitility.Awaitility.await;
+import static org.mockito.Mockito.mock;
+
+class WebFluxStreamableIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String CUSTOM_MESSAGE_ENDPOINT = "/otherPath/mcp/message";
+
+	private DisposableServer httpServer;
+
+	private WebFluxStreamableServerTransportProvider mcpStreamableServerTransportProvider;
+
+	ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
+
+	@BeforeEach
+	public void before() {
+
+		this.mcpStreamableServerTransportProvider = WebFluxStreamableServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
+			.build();
+
+		HttpHandler httpHandler = RouterFunctions
+			.toHttpHandler(mcpStreamableServerTransportProvider.getRouterFunction());
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+						.endpoint(CUSTOM_MESSAGE_ENDPOINT)
+						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
+		clientBuilders
+			.put("webflux", McpClient
+				.sync(WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
+					.endpoint(CUSTOM_MESSAGE_ENDPOINT)
+					.build())
+				.initializationTimeout(Duration.ofHours(10))
+				.requestTimeout(Duration.ofHours(10)));
+
+	}
+
+	@AfterEach
+	public void after() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+	// ---------------------------------------
+	// Sampling Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageWithoutSamplingCapabilities(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> exchange.createMessage(mock(CreateMessageRequest.class))
+				.thenReturn(mock(CallToolResult.class)))
+			.build();
+
+		var server = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.tools(tool)
+			.build();
+
+		try (var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+			.build();) {
+
+			assertThat(client.initialize()).isNotNull();
+
+			try {
+				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class)
+					.hasMessage("Client must be configured with sampling capabilities");
+			}
+		}
+		server.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		AtomicReference samplingResult = new AtomicReference<>();
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = CreateMessageRequest.builder()
+					.messages(List
+						.of(new McpSchema.SamplingMessage(Role.USER, new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				return exchange.createMessage(createMessageRequest)
+					.doOnNext(samplingResult::set)
+					.thenReturn(callResponse);
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+
+			assertWith(samplingResult.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.role()).isEqualTo(Role.USER);
+				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+				assertThat(result.model()).isEqualTo("MockModelName");
+				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+			});
+		}
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws InterruptedException {
+
+		// Client
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		// Server
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		AtomicReference samplingResult = new AtomicReference<>();
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var craeteMessageRequest = CreateMessageRequest.builder()
+					.messages(List
+						.of(new McpSchema.SamplingMessage(Role.USER, new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				return exchange.createMessage(craeteMessageRequest)
+					.doOnNext(samplingResult::set)
+					.thenReturn(callResponse);
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.requestTimeout(Duration.ofSeconds(4))
+			.serverInfo("test-server", "1.0.0")
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+
+			assertWith(samplingResult.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.role()).isEqualTo(Role.USER);
+				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+				assertThat(result.model()).isEqualTo("MockModelName");
+				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+			});
+		}
+
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageWithRequestTimeoutFail(String clientType) throws InterruptedException {
+
+		// Client
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		// Server
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var craeteMessageRequest = CreateMessageRequest.builder()
+					.messages(List
+						.of(new McpSchema.SamplingMessage(Role.USER, new McpSchema.TextContent("Test message"))))
+					.build();
+
+				return exchange.createMessage(craeteMessageRequest).thenReturn(callResponse);
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.requestTimeout(Duration.ofSeconds(1))
+			.serverInfo("test-server", "1.0.0")
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}).withMessageContaining("within 1000ms");
+
+		}
+
+		mcpServer.closeGracefully().block();
+	}
+
+	// ---------------------------------------
+	// Elicitation Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> exchange.createElicitation(mock(ElicitRequest.class))
+				.then(Mono.just(mock(CallToolResult.class))))
+			.build();
+
+		var server = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client without elicitation capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+			try {
+				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class)
+					.hasMessage("Client must be configured with elicitation capabilities");
+			}
+		}
+		server.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+
+			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
+		};
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+		}
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
+
+		// Client
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build();
+
+		// Server
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(3))
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response).isEqualTo(callResponse);
+
+		mcpClient.closeGracefully();
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationWithRequestTimeoutFail(String clientType) {
+
+		var latch = new CountDownLatch(1);
+		// Client
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+
+			try {
+				if (!latch.await(2, TimeUnit.SECONDS)) {
+					throw new RuntimeException("Timeout waiting for elicitation processing");
+				}
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build();
+
+		// Server
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		AtomicReference resultRef = new AtomicReference<>();
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				return exchange.createElicitation(elicitationRequest)
+					.doOnNext(resultRef::set)
+					.then(Mono.just(callResponse));
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1)) // 1 second.
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+		}).withMessageContaining("within 1000ms");
+
+		ElicitResult elicitResult = resultRef.get();
+		assertThat(elicitResult).isNull();
+
+		mcpClient.closeGracefully();
+		mcpServer.closeGracefully().block();
+	}
+
+	// ---------------------------------------
+	// Roots Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(rootsRef.get()).isNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(roots);
+			});
+
+			// Remove a root
+			mcpClient.removeRoot(roots.get(0).uri());
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
+			});
+
+			// Add a new root
+			var root3 = new Root("uri3://", "root3");
+			mcpClient.addRoot(root3);
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsWithoutCapability(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				exchange.listRoots(); // try to list roots
+
+				return mock(CallToolResult.class);
+			})
+			.build();
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.rootsChangeHandler((exchange, rootsUpdate) -> {
+			})
+			.tools(tool)
+			.build();
+
+		// Create client without roots capability
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().build()).build()) {
+
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			// Attempt to list roots should fail
+			try {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
+			}
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsNotificationWithEmptyRootsList(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(List.of()) // Empty roots list
+			.build()) {
+
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).isEmpty();
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsWithMultipleHandlers(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"));
+
+		AtomicReference> rootsRef1 = new AtomicReference<>();
+		AtomicReference> rootsRef2 = new AtomicReference<>();
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef1.set(rootsUpdate))
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef2.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef1.get()).containsAll(roots);
+				assertThat(rootsRef2.get()).containsAll(roots);
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsServerCloseWithActiveSubscription(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"));
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(roots);
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tools Tests
+	// ---------------------------------------
+
+	String emptyJsonSchema = """
+			{
+			"$schema": "http://json-schema.org/draft-07/schema#",
+			"type": "object",
+			"properties": {}
+			}
+			""";
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolCallSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+				// perform a blocking call to a remote service
+				String response = RestClient.create()
+					.get()
+					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
+					.retrieve()
+					.body(String.class);
+				assertThat(response).isNotBlank();
+				return callResponse;
+			})
+			.build();
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolListChangeHandlingSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+				// perform a blocking call to a remote service
+				String response = RestClient.create()
+					.get()
+					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
+					.retrieve()
+					.body(String.class);
+				assertThat(response).isNotBlank();
+				return callResponse;
+			})
+			.build();
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
+			// perform a blocking call to a remote service
+			String response = RestClient.create()
+				.get()
+				.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
+				.retrieve()
+				.body(String.class);
+			assertThat(response).isNotBlank();
+			rootsRef.set(toolsUpdate);
+		}).build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(rootsRef.get()).isNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			mcpServer.notifyToolsListChanged();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
+			});
+
+			// Remove a tool
+			mcpServer.removeTool("tool1");
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).isEmpty();
+			});
+
+			// Add a new tool
+			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
+				.tool(new Tool("tool2", "tool2 description", emptyJsonSchema))
+				.callHandler((exchange, request) -> callResponse)
+				.build();
+
+			mcpServer.addTool(tool2);
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testInitialize(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider).build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Logging Tests
+	// ---------------------------------------
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testLoggingNotification(String clientType) throws InterruptedException {
+		int expectedNotificationsCount = 3;
+		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
+		// Create a list to store received logging notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that sends logging notifications
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("logging-test", "Test logging notifications", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications with different levels
+
+			//@formatter:off
+					return exchange // This should be filtered out (DEBUG < NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.DEBUG)
+								.logger("test-logger")
+								.data("Debug message")
+								.build())
+					.then(exchange // This should be sent (NOTICE >= NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.NOTICE)
+								.logger("test-logger")
+								.data("Notice message")
+								.build()))
+					.then(exchange // This should be sent (ERROR > NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+							.level(McpSchema.LoggingLevel.ERROR)
+							.logger("test-logger")
+							.data("Error message")
+							.build()))
+					.then(exchange // This should be filtered out (INFO < NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.INFO)
+								.logger("test-logger")
+								.data("Another info message")
+								.build()))
+					.then(exchange // This should be sent (ERROR >= NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.ERROR)
+								.logger("test-logger")
+								.data("Another error message")
+								.build()))
+					.thenReturn(new CallToolResult("Logging test completed", false));
+					//@formatter:on
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client with logging notification handler
+				var mcpClient = clientBuilder.loggingConsumer(notification -> {
+					receivedNotifications.add(notification);
+					latch.countDown();
+				}).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Set minimum logging level to NOTICE
+			mcpClient.setLoggingLevel(McpSchema.LoggingLevel.NOTICE);
+
+			// Call the tool that sends logging notifications
+			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Logging test completed");
+
+			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
+
+			// Should have received 3 notifications (1 NOTICE and 2 ERROR)
+			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
+
+			Map notificationMap = receivedNotifications.stream()
+				.collect(Collectors.toMap(n -> n.data(), n -> n));
+
+			// First notification should be NOTICE level
+			assertThat(notificationMap.get("Notice message").level()).isEqualTo(McpSchema.LoggingLevel.NOTICE);
+			assertThat(notificationMap.get("Notice message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Notice message").data()).isEqualTo("Notice message");
+
+			// Second notification should be ERROR level
+			assertThat(notificationMap.get("Error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
+			assertThat(notificationMap.get("Error message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Error message").data()).isEqualTo("Error message");
+
+			// Third notification should be ERROR level
+			assertThat(notificationMap.get("Another error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
+			assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
+		}
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Progress Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testProgressNotification(String clientType) throws InterruptedException {
+		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
+											// token
+		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
+		// Create a list to store received logging notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that sends logging notifications
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder()
+				.name("progress-test")
+				.description("Test progress notifications")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications
+				var progressToken = (String) request.meta().get("progressToken");
+
+				return exchange
+					.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.0, 1.0, "Processing started"))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Processing data")))
+					.then(// Send a progress notification with another progress value
+							// should
+							exchange.progressNotification(new McpSchema.ProgressNotification("another-progress-token",
+									0.0, 1.0, "Another processing started")))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
+					.thenReturn(new CallToolResult(("Progress test completed"), false));
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client with progress notification handler
+				var mcpClient = clientBuilder.progressConsumer(notification -> {
+					receivedNotifications.add(notification);
+					latch.countDown();
+				}).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that sends progress notifications
+			McpSchema.CallToolRequest callToolRequest = McpSchema.CallToolRequest.builder()
+				.name("progress-test")
+				.meta(Map.of("progressToken", "test-progress-token"))
+				.build();
+			CallToolResult result = mcpClient.callTool(callToolRequest);
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
+
+			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
+
+			// Should have received 3 notifications
+			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
+
+			Map notificationMap = receivedNotifications.stream()
+				.collect(Collectors.toMap(n -> n.message(), n -> n));
+
+			// First notification should be 0.0/1.0 progress
+			assertThat(notificationMap.get("Processing started").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing started").message()).isEqualTo("Processing started");
+
+			// Second notification should be 0.5/1.0 progress
+			assertThat(notificationMap.get("Processing data").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing data").progress()).isEqualTo(0.5);
+			assertThat(notificationMap.get("Processing data").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing data").message()).isEqualTo("Processing data");
+
+			// Third notification should be another progress token with 0.0/1.0 progress
+			assertThat(notificationMap.get("Another processing started").progressToken())
+				.isEqualTo("another-progress-token");
+			assertThat(notificationMap.get("Another processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Another processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Another processing started").message())
+				.isEqualTo("Another processing started");
+
+			// Fourth notification should be 1.0/1.0 progress
+			assertThat(notificationMap.get("Processing completed").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing completed").progress()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
+		}
+		finally {
+			mcpServer.close();
+		}
+	}
+
+	// ---------------------------------------
+	// Completion Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : Completion call")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var expectedValues = List.of("python", "pytorch", "pyside");
+		var completionResponse = new CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
+				true // hasMore
+		));
+
+		AtomicReference samplingRequest = new AtomicReference<>();
+		BiFunction completionHandler = (mcpSyncServerExchange,
+				request) -> {
+			samplingRequest.set(request);
+			return completionResponse;
+		};
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().completions().build())
+			.prompts(new McpServerFeatures.SyncPromptSpecification(
+					new Prompt("code_review", "Code review", "this is code review prompt",
+							List.of(new PromptArgument("language", "Language", "string", false))),
+					(mcpSyncServerExchange, getPromptRequest) -> null))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(
+					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CompleteRequest request = new CompleteRequest(
+					new PromptReference("ref/prompt", "code_review", "Code review"),
+					new CompleteRequest.CompleteArgument("language", "py"));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			assertThat(result).isNotNull();
+
+			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
+			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Ping Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testPingSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that uses ping functionality
+		AtomicReference executionOrder = new AtomicReference<>("");
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(new Tool("ping-async-test", "Test ping async behavior", emptyJsonSchema))
+			.callHandler((exchange, request) -> {
+
+				executionOrder.set(executionOrder.get() + "1");
+
+				// Test async ping behavior
+				return exchange.ping().doOnNext(result -> {
+
+					assertThat(result).isNotNull();
+					// Ping should return an empty object or map
+					assertThat(result).isInstanceOf(Map.class);
+
+					executionOrder.set(executionOrder.get() + "2");
+					assertThat(result).isNotNull();
+				}).then(Mono.fromCallable(() -> {
+					executionOrder.set(executionOrder.get() + "3");
+					return new CallToolResult("Async ping test completed", false);
+				}));
+			})
+			.build();
+
+		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that tests ping async behavior
+			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("ping-async-test", Map.of()));
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Async ping test completed");
+
+			// Verify execution order
+			assertThat(executionOrder.get()).isEqualTo("123");
+		}
+
+		mcpServer.closeGracefully().block();
+	}
+
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					String expression = (String) request.getOrDefault("expression", "2 + 3");
+					double result = evaluateExpression(expression);
+					return CallToolResult.builder()
+						.structuredContent(
+								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationFailure(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return invalid structured output. Result should be number, missing
+					// operation
+					return CallToolResult.builder()
+						.addTextContent("Invalid calculation")
+						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputMissingStructuredContent(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
+				(exchange, request) -> {
+					// Return result without structured content but tool has output schema
+					return CallToolResult.builder().addTextContent("Calculation completed").build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.instructions("bla")
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputRuntimeToolAddition(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Start server without tools
+		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
+					(exchange, request) -> {
+						int count = (Integer) request.getOrDefault("count", 1);
+						return CallToolResult.builder()
+							.addTextContent("Dynamic tool executed " + count + " times")
+							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+							.build();
+					});
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java
index cc33e7b94..a3bdf10b0 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java
@@ -29,8 +29,7 @@ class WebFluxSseMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
 
 	private DisposableServer httpServer;
 
-	@Override
-	protected McpServerTransportProvider createMcpTransportProvider() {
+	private McpServerTransportProvider createMcpTransportProvider() {
 		var transportProvider = new WebFluxSseServerTransportProvider.Builder().objectMapper(new ObjectMapper())
 			.messageEndpoint(MESSAGE_ENDPOINT)
 			.build();
@@ -41,6 +40,11 @@ protected McpServerTransportProvider createMcpTransportProvider() {
 		return transportProvider;
 	}
 
+	@Override
+	protected McpServer.AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(createMcpTransportProvider());
+	}
+
 	@Override
 	protected void onStart() {
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java
index 2fc104538..3e28e96b8 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java
@@ -32,7 +32,11 @@ class WebFluxSseMcpSyncServerTests extends AbstractMcpSyncServerTests {
 	private WebFluxSseServerTransportProvider transportProvider;
 
 	@Override
-	protected McpServerTransportProvider createMcpTransportProvider() {
+	protected McpServer.SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(createMcpTransportProvider());
+	}
+
+	private McpServerTransportProvider createMcpTransportProvider() {
 		transportProvider = new WebFluxSseServerTransportProvider.Builder().objectMapper(new ObjectMapper())
 			.messageEndpoint(MESSAGE_ENDPOINT)
 			.build();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
new file mode 100644
index 000000000..928bd812d
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
@@ -0,0 +1,63 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import org.junit.jupiter.api.Timeout;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+/**
+ * Tests for {@link McpAsyncServer} using
+ * {@link WebFluxStreamableServerTransportProvider}.
+ *
+ * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
+ */
+@Timeout(15) // Giving extra time beyond the client timeout
+class WebFluxStreamableMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String MESSAGE_ENDPOINT = "/mcp/message";
+
+	private DisposableServer httpServer;
+
+	private McpStreamableServerTransportProvider createMcpTransportProvider() {
+		var transportProvider = WebFluxStreamableServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(MESSAGE_ENDPOINT)
+			.build();
+
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(transportProvider.getRouterFunction());
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+		return transportProvider;
+	}
+
+	@Override
+	protected McpServer.AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(createMcpTransportProvider());
+	}
+
+	@Override
+	protected void onStart() {
+	}
+
+	@Override
+	protected void onClose() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
new file mode 100644
index 000000000..e82e384c4
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
@@ -0,0 +1,62 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import org.junit.jupiter.api.Timeout;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+/**
+ * Tests for {@link McpAsyncServer} using
+ * {@link WebFluxStreamableServerTransportProvider}.
+ *
+ * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
+ */
+@Timeout(15) // Giving extra time beyond the client timeout
+class WebFluxStreamableMcpSyncServerTests extends AbstractMcpSyncServerTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String MESSAGE_ENDPOINT = "/mcp/message";
+
+	private DisposableServer httpServer;
+
+	private McpStreamableServerTransportProvider createMcpTransportProvider() {
+		var transportProvider = WebFluxStreamableServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(MESSAGE_ENDPOINT)
+			.build();
+
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(transportProvider.getRouterFunction());
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+		return transportProvider;
+	}
+
+	@Override
+	protected McpServer.SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(createMcpTransportProvider());
+	}
+
+	@Override
+	protected void onStart() {
+	}
+
+	@Override
+	protected void onClose() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java
index 6a6ad17e9..bb4c2bf37 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java
@@ -49,8 +49,7 @@ public RouterFunction routerFunction(WebMvcSseServerTransportPro
 
 	private AnnotationConfigWebApplicationContext appContext;
 
-	@Override
-	protected McpServerTransportProvider createMcpTransportProvider() {
+	private McpServerTransportProvider createMcpTransportProvider() {
 		// Set up Tomcat first
 		tomcat = new Tomcat();
 		tomcat.setPort(PORT);
@@ -90,6 +89,11 @@ protected McpServerTransportProvider createMcpTransportProvider() {
 		return transportProvider;
 	}
 
+	@Override
+	protected McpServer.AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(createMcpTransportProvider());
+	}
+
 	@Override
 	protected void onStart() {
 	}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
index 1964703c1..7e49ddf3b 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
@@ -49,7 +49,11 @@ public RouterFunction routerFunction(WebMvcSseServerTransportPro
 	private AnnotationConfigWebApplicationContext appContext;
 
 	@Override
-	protected WebMvcSseServerTransportProvider createMcpTransportProvider() {
+	protected McpServer.SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(createMcpTransportProvider());
+	}
+
+	private WebMvcSseServerTransportProvider createMcpTransportProvider() {
 		// Set up Tomcat first
 		tomcat = new Tomcat();
 		tomcat.setPort(PORT);
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index eb08bdcde..1e87d4420 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -21,6 +21,8 @@
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
@@ -42,7 +44,7 @@ public abstract class AbstractMcpAsyncServerTests {
 
 	private static final String TEST_PROMPT_NAME = "test-prompt";
 
-	abstract protected McpServerTransportProvider createMcpTransportProvider();
+	abstract protected McpServer.AsyncSpecification prepareAsyncServerBuilder();
 
 	protected void onStart() {
 	}
@@ -63,28 +65,29 @@ void tearDown() {
 	// Server Lifecycle Tests
 	// ---------------------------------------
 
-	@Test
-	void testConstructorWithInvalidArguments() {
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "sse", "streamable" })
+	void testConstructorWithInvalidArguments(String serverType) {
 		assertThatThrownBy(() -> McpServer.async((McpServerTransportProvider) null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Transport provider must not be null");
 
-		assertThatThrownBy(
-				() -> McpServer.async(createMcpTransportProvider()).serverInfo((McpSchema.Implementation) null))
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo((McpSchema.Implementation) null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Server info must not be null");
 	}
 
 	@Test
 	void testGracefulShutdown() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		McpServer.AsyncSpecification builder = prepareAsyncServerBuilder();
+		var mcpAsyncServer = builder.serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(mcpAsyncServer.closeGracefully()).verifyComplete();
 	}
 
 	@Test
 	void testImmediateClose() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpAsyncServer.close()).doesNotThrowAnyException();
 	}
@@ -104,8 +107,7 @@ void testImmediateClose() {
 	@Deprecated
 	void testAddTool() {
 		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -119,8 +121,7 @@ void testAddTool() {
 	@Test
 	void testAddToolCall() {
 		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -137,8 +138,7 @@ void testAddToolCall() {
 	void testAddDuplicateTool() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tool(duplicateTool, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -158,8 +158,7 @@ void testAddDuplicateTool() {
 	void testAddDuplicateToolCall() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -180,8 +179,7 @@ void testDuplicateToolCallDuringBuilding() {
 		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
 				emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) // Duplicate!
@@ -203,8 +201,7 @@ void testDuplicateToolsInBatchListRegistration() {
 					.build() // Duplicate!
 		);
 
-		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(specs)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -215,8 +212,7 @@ void testDuplicateToolsInBatchListRegistration() {
 	void testDuplicateToolsInBatchVarargsRegistration() {
 		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.AsyncToolSpecification.builder()
 				.tool(duplicateTool)
@@ -235,8 +231,7 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 	void testRemoveTool() {
 		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -248,8 +243,7 @@ void testRemoveTool() {
 
 	@Test
 	void testRemoveNonexistentTool() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -264,8 +258,7 @@ void testRemoveNonexistentTool() {
 	void testNotifyToolsListChanged() {
 		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -281,7 +274,7 @@ void testNotifyToolsListChanged() {
 
 	@Test
 	void testNotifyResourcesListChanged() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(mcpAsyncServer.notifyResourcesListChanged()).verifyComplete();
 
@@ -290,7 +283,7 @@ void testNotifyResourcesListChanged() {
 
 	@Test
 	void testNotifyResourcesUpdated() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier
 			.create(mcpAsyncServer
@@ -302,8 +295,7 @@ void testNotifyResourcesUpdated() {
 
 	@Test
 	void testAddResource() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -319,8 +311,7 @@ void testAddResource() {
 
 	@Test
 	void testAddResourceWithNullSpecification() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -335,9 +326,7 @@ void testAddResourceWithNullSpecification() {
 	@Test
 	void testAddResourceWithoutCapability() {
 		// Create a server without resource capabilities
-		McpAsyncServer serverWithoutResources = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
 				null);
@@ -353,9 +342,7 @@ void testAddResourceWithoutCapability() {
 	@Test
 	void testRemoveResourceWithoutCapability() {
 		// Create a server without resource capabilities
-		McpAsyncServer serverWithoutResources = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutResources.removeResource(TEST_RESOURCE_URI)).verifyErrorSatisfies(error -> {
 			assertThat(error).isInstanceOf(McpError.class)
@@ -369,7 +356,7 @@ void testRemoveResourceWithoutCapability() {
 
 	@Test
 	void testNotifyPromptsListChanged() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(mcpAsyncServer.notifyPromptsListChanged()).verifyComplete();
 
@@ -378,8 +365,7 @@ void testNotifyPromptsListChanged() {
 
 	@Test
 	void testAddPromptWithNullSpecification() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(false).build())
 			.build();
 
@@ -392,9 +378,7 @@ void testAddPromptWithNullSpecification() {
 	@Test
 	void testAddPromptWithoutCapability() {
 		// Create a server without prompt capabilities
-		McpAsyncServer serverWithoutPrompts = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutPrompts = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of());
 		McpServerFeatures.AsyncPromptSpecification specification = new McpServerFeatures.AsyncPromptSpecification(
@@ -410,9 +394,7 @@ void testAddPromptWithoutCapability() {
 	@Test
 	void testRemovePromptWithoutCapability() {
 		// Create a server without prompt capabilities
-		McpAsyncServer serverWithoutPrompts = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutPrompts = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).verifyErrorSatisfies(error -> {
 			assertThat(error).isInstanceOf(McpError.class)
@@ -429,8 +411,7 @@ void testRemovePrompt() {
 				prompt, (exchange, req) -> Mono.just(new GetPromptResult("Test prompt description", List
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))));
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.prompts(specification)
 			.build();
@@ -442,8 +423,7 @@ void testRemovePrompt() {
 
 	@Test
 	void testRemoveNonexistentPrompt() {
-		var mcpAsyncServer2 = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer2 = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
@@ -466,8 +446,7 @@ void testRootsChangeHandlers() {
 		var rootsReceived = new McpSchema.Root[1];
 		var consumerCalled = new boolean[1];
 
-		var singleConsumerServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var singleConsumerServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> Mono.fromRunnable(() -> {
 				consumerCalled[0] = true;
 				if (!roots.isEmpty()) {
@@ -486,8 +465,7 @@ void testRootsChangeHandlers() {
 		var consumer2Called = new boolean[1];
 		var rootsContent = new List[1];
 
-		var multipleConsumersServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var multipleConsumersServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> Mono.fromRunnable(() -> {
 				consumer1Called[0] = true;
 				rootsContent[0] = roots;
@@ -500,8 +478,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test error handling
-		var errorHandlingServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var errorHandlingServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				throw new RuntimeException("Test error");
 			}))
@@ -513,9 +490,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test without consumers
-		var noConsumersServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var noConsumersServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(noConsumersServer).isNotNull();
 		assertThatCode(() -> noConsumersServer.closeGracefully().block(Duration.ofSeconds(10)))
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 4d5f9f772..5d70ae4c0 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -28,7 +28,7 @@
 
 /**
  * Test suite for the {@link McpSyncServer} that can be used with different
- * {@link McpTransportProvider} implementations.
+ * {@link McpServerTransportProvider} implementations.
  *
  * @author Christian Tzolov
  */
@@ -40,7 +40,7 @@ public abstract class AbstractMcpSyncServerTests {
 
 	private static final String TEST_PROMPT_NAME = "test-prompt";
 
-	abstract protected McpServerTransportProvider createMcpTransportProvider();
+	abstract protected McpServer.SyncSpecification prepareSyncServerBuilder();
 
 	protected void onStart() {
 	}
@@ -68,28 +68,28 @@ void testConstructorWithInvalidArguments() {
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Transport provider must not be null");
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider()).serverInfo(null))
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo(null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Server info must not be null");
 	}
 
 	@Test
 	void testGracefulShutdown() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testImmediateClose() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.close()).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testGetAsyncServer() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(mcpSyncServer.getAsyncServer()).isNotNull();
 
@@ -111,8 +111,7 @@ void testGetAsyncServer() {
 	@Test
 	@Deprecated
 	void testAddTool() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -126,8 +125,7 @@ void testAddTool() {
 
 	@Test
 	void testAddToolCall() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -145,8 +143,7 @@ void testAddToolCall() {
 	void testAddDuplicateTool() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tool(duplicateTool, (exchange, args) -> new CallToolResult(List.of(), false))
 			.build();
@@ -163,8 +160,7 @@ void testAddDuplicateTool() {
 	void testAddDuplicateToolCall() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
 			.build();
@@ -183,8 +179,7 @@ void testDuplicateToolCallDuringBuilding() {
 		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
 				emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) // Duplicate!
@@ -206,8 +201,7 @@ void testDuplicateToolsInBatchListRegistration() {
 					.build() // Duplicate!
 		);
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(specs)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -218,8 +212,7 @@ void testDuplicateToolsInBatchListRegistration() {
 	void testDuplicateToolsInBatchVarargsRegistration() {
 		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.SyncToolSpecification.builder()
 				.tool(duplicateTool)
@@ -238,8 +231,7 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 	void testRemoveTool() {
 		Tool tool = new McpSchema.Tool(TEST_TOOL_NAME, "Test tool", emptyJsonSchema);
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(tool, (exchange, args) -> new CallToolResult(List.of(), false))
 			.build();
@@ -251,8 +243,7 @@ void testRemoveTool() {
 
 	@Test
 	void testRemoveNonexistentTool() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -264,7 +255,7 @@ void testRemoveNonexistentTool() {
 
 	@Test
 	void testNotifyToolsListChanged() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.notifyToolsListChanged()).doesNotThrowAnyException();
 
@@ -277,7 +268,7 @@ void testNotifyToolsListChanged() {
 
 	@Test
 	void testNotifyResourcesListChanged() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.notifyResourcesListChanged()).doesNotThrowAnyException();
 
@@ -286,7 +277,7 @@ void testNotifyResourcesListChanged() {
 
 	@Test
 	void testNotifyResourcesUpdated() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer
 			.notifyResourcesUpdated(new McpSchema.ResourcesUpdatedNotification(TEST_RESOURCE_URI)))
@@ -297,8 +288,7 @@ void testNotifyResourcesUpdated() {
 
 	@Test
 	void testAddResource() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -314,8 +304,7 @@ void testAddResource() {
 
 	@Test
 	void testAddResourceWithNullSpecification() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -328,9 +317,7 @@ void testAddResourceWithNullSpecification() {
 
 	@Test
 	void testAddResourceWithoutCapability() {
-		var serverWithoutResources = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
 				null);
@@ -343,9 +330,7 @@ void testAddResourceWithoutCapability() {
 
 	@Test
 	void testRemoveResourceWithoutCapability() {
-		var serverWithoutResources = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI)).isInstanceOf(McpError.class)
 			.hasMessage("Server must be configured with resource capabilities");
@@ -357,7 +342,7 @@ void testRemoveResourceWithoutCapability() {
 
 	@Test
 	void testNotifyPromptsListChanged() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.notifyPromptsListChanged()).doesNotThrowAnyException();
 
@@ -366,8 +351,7 @@ void testNotifyPromptsListChanged() {
 
 	@Test
 	void testAddPromptWithNullSpecification() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(false).build())
 			.build();
 
@@ -378,9 +362,7 @@ void testAddPromptWithNullSpecification() {
 
 	@Test
 	void testAddPromptWithoutCapability() {
-		var serverWithoutPrompts = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutPrompts = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of());
 		McpServerFeatures.SyncPromptSpecification specification = new McpServerFeatures.SyncPromptSpecification(prompt,
@@ -393,9 +375,7 @@ void testAddPromptWithoutCapability() {
 
 	@Test
 	void testRemovePromptWithoutCapability() {
-		var serverWithoutPrompts = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutPrompts = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).isInstanceOf(McpError.class)
 			.hasMessage("Server must be configured with prompt capabilities");
@@ -408,8 +388,7 @@ void testRemovePrompt() {
 				(exchange, req) -> new GetPromptResult("Test prompt description", List
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))));
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.prompts(specification)
 			.build();
@@ -421,8 +400,7 @@ void testRemovePrompt() {
 
 	@Test
 	void testRemoveNonexistentPrompt() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
@@ -442,8 +420,7 @@ void testRootsChangeHandlers() {
 		var rootsReceived = new McpSchema.Root[1];
 		var consumerCalled = new boolean[1];
 
-		var singleConsumerServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var singleConsumerServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				consumerCalled[0] = true;
 				if (!roots.isEmpty()) {
@@ -461,8 +438,7 @@ void testRootsChangeHandlers() {
 		var consumer2Called = new boolean[1];
 		var rootsContent = new List[1];
 
-		var multipleConsumersServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var multipleConsumersServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				consumer1Called[0] = true;
 				rootsContent[0] = roots;
@@ -474,8 +450,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test error handling
-		var errorHandlingServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var errorHandlingServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				throw new RuntimeException("Test error");
 			}))
@@ -486,7 +461,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test without consumers
-		var noConsumersServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var noConsumersServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(noConsumersServer).isNotNull();
 		assertThatCode(() -> noConsumersServer.closeGracefully()).doesNotThrowAnyException();
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
new file mode 100644
index 000000000..234a1d4a0
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
@@ -0,0 +1,50 @@
+package io.modelcontextprotocol.server;
+
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+import java.util.Map;
+
+class DefaultMcpStatelessServerHandler implements McpStatelessServerHandler {
+
+	private static final Logger logger = LoggerFactory.getLogger(DefaultMcpStatelessServerHandler.class);
+
+	Map> requestHandlers;
+
+	Map notificationHandlers;
+
+	public DefaultMcpStatelessServerHandler(Map> requestHandlers,
+			Map notificationHandlers) {
+		this.requestHandlers = requestHandlers;
+		this.notificationHandlers = notificationHandlers;
+	}
+
+	@Override
+	public Mono handleRequest(McpTransportContext transportContext,
+			McpSchema.JSONRPCRequest request) {
+		McpStatelessRequestHandler requestHandler = this.requestHandlers.get(request.method());
+		if (requestHandler == null) {
+			return Mono.error(new McpError("Missing handler for request type: " + request.method()));
+		}
+		return requestHandler.handle(transportContext, request.params())
+			.map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), result, null))
+			.onErrorResume(t -> Mono.just(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null,
+					new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR, t.getMessage(),
+							null))));
+	}
+
+	@Override
+	public Mono handleNotification(McpTransportContext transportContext,
+			McpSchema.JSONRPCNotification notification) {
+		McpStatelessNotificationHandler notificationHandler = this.notificationHandlers.get(notification.method());
+		if (notificationHandler == null) {
+			logger.warn("Missing handler for notification type: {}", notification.method());
+			return Mono.empty();
+		}
+		return notificationHandler.handle(transportContext, notification.params());
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
new file mode 100644
index 000000000..300bdf711
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
@@ -0,0 +1,45 @@
+package io.modelcontextprotocol.server;
+
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Default implementation for {@link McpTransportContext} which uses a Thread-safe map.
+ * Objects of this kind are mutable.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class DefaultMcpTransportContext implements McpTransportContext {
+
+	private final Map storage;
+
+	/**
+	 * Create an empty instance.
+	 */
+	public DefaultMcpTransportContext() {
+		this.storage = new ConcurrentHashMap<>();
+	}
+
+	DefaultMcpTransportContext(Map storage) {
+		this.storage = storage;
+	}
+
+	@Override
+	public Object get(String key) {
+		return this.storage.get(key);
+	}
+
+	@Override
+	public void put(String key, Object value) {
+		this.storage.put(key, value);
+	}
+
+	/**
+	 * Allows copying the contents.
+	 * @return new instance with the copy of the underlying map
+	 */
+	public McpTransportContext copy() {
+		return new DefaultMcpTransportContext(new ConcurrentHashMap<>(this.storage));
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index 7131b10fa..fcd42a433 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -15,6 +15,9 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.BiFunction;
 
+import io.modelcontextprotocol.spec.DefaultMcpStreamableServerSessionFactory;
+import io.modelcontextprotocol.spec.McpServerTransportProviderBase;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -86,7 +89,7 @@ public class McpAsyncServer {
 
 	private static final Logger logger = LoggerFactory.getLogger(McpAsyncServer.class);
 
-	private final McpServerTransportProvider mcpTransportProvider;
+	private final McpServerTransportProviderBase mcpTransportProvider;
 
 	private final ObjectMapper objectMapper;
 
@@ -139,7 +142,56 @@ public class McpAsyncServer {
 		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
 		this.jsonSchemaValidator = jsonSchemaValidator;
 
-		Map> requestHandlers = new HashMap<>();
+		Map> requestHandlers = prepareRequestHandlers();
+		Map notificationHandlers = prepareNotificationHandlers(features);
+
+		mcpTransportProvider.setSessionFactory(transport -> new McpServerSession(UUID.randomUUID().toString(),
+				requestTimeout, transport, this::asyncInitializeRequestHandler, requestHandlers, notificationHandlers));
+	}
+
+	McpAsyncServer(McpStreamableServerTransportProvider mcpTransportProvider, ObjectMapper objectMapper,
+			McpServerFeatures.Async features, Duration requestTimeout,
+			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator) {
+		this.mcpTransportProvider = mcpTransportProvider;
+		this.objectMapper = objectMapper;
+		this.serverInfo = features.serverInfo();
+		this.serverCapabilities = features.serverCapabilities();
+		this.instructions = features.instructions();
+		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
+		this.resources.putAll(features.resources());
+		this.resourceTemplates.addAll(features.resourceTemplates());
+		this.prompts.putAll(features.prompts());
+		this.completions.putAll(features.completions());
+		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+		this.jsonSchemaValidator = jsonSchemaValidator;
+
+		Map> requestHandlers = prepareRequestHandlers();
+		Map notificationHandlers = prepareNotificationHandlers(features);
+
+		mcpTransportProvider.setSessionFactory(new DefaultMcpStreamableServerSessionFactory(requestTimeout,
+				this::asyncInitializeRequestHandler, requestHandlers, notificationHandlers));
+	}
+
+	private Map prepareNotificationHandlers(McpServerFeatures.Async features) {
+		Map notificationHandlers = new HashMap<>();
+
+		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_INITIALIZED, (exchange, params) -> Mono.empty());
+
+		List, Mono>> rootsChangeConsumers = features
+			.rootsChangeConsumers();
+
+		if (Utils.isEmpty(rootsChangeConsumers)) {
+			rootsChangeConsumers = List.of((exchange, roots) -> Mono.fromRunnable(() -> logger
+				.warn("Roots list changed notification, but no consumers provided. Roots list changed: {}", roots)));
+		}
+
+		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_ROOTS_LIST_CHANGED,
+				asyncRootsListChangedNotificationHandler(rootsChangeConsumers));
+		return notificationHandlers;
+	}
+
+	private Map> prepareRequestHandlers() {
+		Map> requestHandlers = new HashMap<>();
 
 		// Initialize request handlers for standard MCP methods
 
@@ -174,25 +226,7 @@ public class McpAsyncServer {
 		if (this.serverCapabilities.completions() != null) {
 			requestHandlers.put(McpSchema.METHOD_COMPLETION_COMPLETE, completionCompleteRequestHandler());
 		}
-
-		Map notificationHandlers = new HashMap<>();
-
-		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_INITIALIZED, (exchange, params) -> Mono.empty());
-
-		List, Mono>> rootsChangeConsumers = features
-			.rootsChangeConsumers();
-
-		if (Utils.isEmpty(rootsChangeConsumers)) {
-			rootsChangeConsumers = List.of((exchange, roots) -> Mono.fromRunnable(() -> logger
-				.warn("Roots list changed notification, but no consumers provided. Roots list changed: {}", roots)));
-		}
-
-		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_ROOTS_LIST_CHANGED,
-				asyncRootsListChangedNotificationHandler(rootsChangeConsumers));
-
-		mcpTransportProvider.setSessionFactory(
-				transport -> new McpServerSession(UUID.randomUUID().toString(), requestTimeout, transport,
-						this::asyncInitializeRequestHandler, Mono::empty, requestHandlers, notificationHandlers));
+		return requestHandlers;
 	}
 
 	// ---------------------------------------
@@ -258,7 +292,7 @@ public void close() {
 		this.mcpTransportProvider.close();
 	}
 
-	private McpServerSession.NotificationHandler asyncRootsListChangedNotificationHandler(
+	private McpNotificationHandler asyncRootsListChangedNotificationHandler(
 			List, Mono>> rootsChangeConsumers) {
 		return (exchange, params) -> exchange.listRoots()
 			.flatMap(listRootsResult -> Flux.fromIterable(rootsChangeConsumers)
@@ -450,7 +484,7 @@ public Mono notifyToolsListChanged() {
 		return this.mcpTransportProvider.notifyClients(McpSchema.METHOD_NOTIFICATION_TOOLS_LIST_CHANGED, null);
 	}
 
-	private McpServerSession.RequestHandler toolsListRequestHandler() {
+	private McpRequestHandler toolsListRequestHandler() {
 		return (exchange, params) -> {
 			List tools = this.tools.stream().map(McpServerFeatures.AsyncToolSpecification::tool).toList();
 
@@ -458,7 +492,7 @@ private McpServerSession.RequestHandler toolsListRequ
 		};
 	}
 
-	private McpServerSession.RequestHandler toolsCallRequestHandler() {
+	private McpRequestHandler toolsCallRequestHandler() {
 		return (exchange, params) -> {
 			McpSchema.CallToolRequest callToolRequest = objectMapper.convertValue(params,
 					new TypeReference() {
@@ -551,7 +585,7 @@ public Mono notifyResourcesUpdated(McpSchema.ResourcesUpdatedNotification
 				resourcesUpdatedNotification);
 	}
 
-	private McpServerSession.RequestHandler resourcesListRequestHandler() {
+	private McpRequestHandler resourcesListRequestHandler() {
 		return (exchange, params) -> {
 			var resourceList = this.resources.values()
 				.stream()
@@ -561,7 +595,7 @@ private McpServerSession.RequestHandler resources
 		};
 	}
 
-	private McpServerSession.RequestHandler resourceTemplateListRequestHandler() {
+	private McpRequestHandler resourceTemplateListRequestHandler() {
 		return (exchange, params) -> Mono
 			.just(new McpSchema.ListResourceTemplatesResult(this.getResourceTemplates(), null));
 
@@ -585,7 +619,7 @@ private List getResourceTemplates() {
 		return list;
 	}
 
-	private McpServerSession.RequestHandler resourcesReadRequestHandler() {
+	private McpRequestHandler resourcesReadRequestHandler() {
 		return (exchange, params) -> {
 			McpSchema.ReadResourceRequest resourceRequest = objectMapper.convertValue(params,
 					new TypeReference() {
@@ -678,7 +712,7 @@ public Mono notifyPromptsListChanged() {
 		return this.mcpTransportProvider.notifyClients(McpSchema.METHOD_NOTIFICATION_PROMPTS_LIST_CHANGED, null);
 	}
 
-	private McpServerSession.RequestHandler promptsListRequestHandler() {
+	private McpRequestHandler promptsListRequestHandler() {
 		return (exchange, params) -> {
 			// TODO: Implement pagination
 			// McpSchema.PaginatedRequest request = objectMapper.convertValue(params,
@@ -694,7 +728,7 @@ private McpServerSession.RequestHandler promptsList
 		};
 	}
 
-	private McpServerSession.RequestHandler promptsGetRequestHandler() {
+	private McpRequestHandler promptsGetRequestHandler() {
 		return (exchange, params) -> {
 			McpSchema.GetPromptRequest promptRequest = objectMapper.convertValue(params,
 					new TypeReference() {
@@ -740,7 +774,7 @@ public Mono loggingNotification(LoggingMessageNotification loggingMessageN
 				loggingMessageNotification);
 	}
 
-	private McpServerSession.RequestHandler setLoggerRequestHandler() {
+	private McpRequestHandler setLoggerRequestHandler() {
 		return (exchange, params) -> {
 			return Mono.defer(() -> {
 
@@ -759,7 +793,7 @@ private McpServerSession.RequestHandler setLoggerRequestHandler() {
 		};
 	}
 
-	private McpServerSession.RequestHandler completionCompleteRequestHandler() {
+	private McpRequestHandler completionCompleteRequestHandler() {
 		return (exchange, params) -> {
 			McpSchema.CompleteRequest request = parseCompletionParams(params);
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
index c0923e10e..61d60bacc 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
@@ -9,10 +9,11 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpLoggableSession;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.LoggingLevel;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
-import io.modelcontextprotocol.spec.McpServerSession;
+import io.modelcontextprotocol.spec.McpSession;
 import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Mono;
 
@@ -25,13 +26,15 @@
  */
 public class McpAsyncServerExchange {
 
-	private final McpServerSession session;
+	private final String sessionId;
+
+	private final McpLoggableSession session;
 
 	private final McpSchema.ClientCapabilities clientCapabilities;
 
 	private final McpSchema.Implementation clientInfo;
 
-	private volatile LoggingLevel minLoggingLevel = LoggingLevel.INFO;
+	private final McpTransportContext transportContext;
 
 	private static final TypeReference CREATE_MESSAGE_RESULT_TYPE_REF = new TypeReference<>() {
 	};
@@ -51,12 +54,39 @@ public class McpAsyncServerExchange {
 	 * @param clientCapabilities The client capabilities that define the supported
 	 * features and functionality.
 	 * @param clientInfo The client implementation information.
+	 * @deprecated Use
+	 * {@link #McpAsyncServerExchange(String, McpLoggableSession, McpSchema.ClientCapabilities, McpSchema.Implementation, McpTransportContext)}
 	 */
-	public McpAsyncServerExchange(McpServerSession session, McpSchema.ClientCapabilities clientCapabilities,
+	@Deprecated
+	public McpAsyncServerExchange(McpSession session, McpSchema.ClientCapabilities clientCapabilities,
 			McpSchema.Implementation clientInfo) {
+		this.sessionId = null;
+		if (!(session instanceof McpLoggableSession)) {
+			throw new IllegalArgumentException("Expecting session to be a McpLoggableSession instance");
+		}
+		this.session = (McpLoggableSession) session;
+		this.clientCapabilities = clientCapabilities;
+		this.clientInfo = clientInfo;
+		this.transportContext = McpTransportContext.EMPTY;
+	}
+
+	/**
+	 * Create a new asynchronous exchange with the client.
+	 * @param session The server session representing a 1-1 interaction.
+	 * @param clientCapabilities The client capabilities that define the supported
+	 * features and functionality.
+	 * @param clientInfo The client implementation information.
+	 * @param transportContext context associated with the client as extracted from the
+	 * transport
+	 */
+	public McpAsyncServerExchange(String sessionId, McpLoggableSession session,
+			McpSchema.ClientCapabilities clientCapabilities, McpSchema.Implementation clientInfo,
+			McpTransportContext transportContext) {
+		this.sessionId = sessionId;
 		this.session = session;
 		this.clientCapabilities = clientCapabilities;
 		this.clientInfo = clientInfo;
+		this.transportContext = transportContext;
 	}
 
 	/**
@@ -75,6 +105,24 @@ public McpSchema.Implementation getClientInfo() {
 		return this.clientInfo;
 	}
 
+	/**
+	 * Provides the {@link McpTransportContext} associated with the transport layer. For
+	 * HTTP transports it can contain the metadata associated with the HTTP request that
+	 * triggered the processing.
+	 * @return the transport context object
+	 */
+	public McpTransportContext transportContext() {
+		return this.transportContext;
+	}
+
+	/**
+	 * Provides the Session ID.
+	 * @return session ID string
+	 */
+	public String sessionId() {
+		return this.sessionId;
+	}
+
 	/**
 	 * Create a new message using the sampling capabilities of the client. The Model
 	 * Context Protocol (MCP) provides a standardized way for servers to request LLM
@@ -170,7 +218,7 @@ public Mono loggingNotification(LoggingMessageNotification loggingMessageN
 		}
 
 		return Mono.defer(() -> {
-			if (this.isNotificationForLevelAllowed(loggingMessageNotification.level())) {
+			if (this.session.isNotificationForLevelAllowed(loggingMessageNotification.level())) {
 				return this.session.sendNotification(McpSchema.METHOD_NOTIFICATION_MESSAGE, loggingMessageNotification);
 			}
 			return Mono.empty();
@@ -205,11 +253,7 @@ public Mono ping() {
 	 */
 	void setMinLoggingLevel(LoggingLevel minLoggingLevel) {
 		Assert.notNull(minLoggingLevel, "minLoggingLevel must not be null");
-		this.minLoggingLevel = minLoggingLevel;
-	}
-
-	private boolean isNotificationForLevelAllowed(LoggingLevel loggingLevel) {
-		return loggingLevel.level() >= this.minLoggingLevel.level();
+		this.session.setMinLoggingLevel(minLoggingLevel);
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
new file mode 100644
index 000000000..609744637
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
@@ -0,0 +1,18 @@
+package io.modelcontextprotocol.server;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import reactor.core.publisher.Mono;
+
+/**
+ * Request handler for the initialization request.
+ */
+public interface McpInitRequestHandler {
+
+	/**
+	 * Handles the initialization request.
+	 * @param initializeRequest the initialization request by the client
+	 * @return a Mono that will emit the result of the initialization
+	 */
+	Mono handle(McpSchema.InitializeRequest initializeRequest);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java
new file mode 100644
index 000000000..6b1061c03
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java
@@ -0,0 +1,19 @@
+package io.modelcontextprotocol.server;
+
+import reactor.core.publisher.Mono;
+
+/**
+ * A handler for client-initiated notifications.
+ */
+public interface McpNotificationHandler {
+
+	/**
+	 * Handles a notification from the client.
+	 * @param exchange the exchange associated with the client that allows calling back to
+	 * the connected client or inspecting its capabilities.
+	 * @param params the parameters of the notification.
+	 * @return a Mono that completes once the notification is handled.
+	 */
+	Mono handle(McpAsyncServerExchange exchange, Object params);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java
new file mode 100644
index 000000000..c9d70ad04
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java
@@ -0,0 +1,22 @@
+package io.modelcontextprotocol.server;
+
+import reactor.core.publisher.Mono;
+
+/**
+ * A handler for client-initiated requests.
+ *
+ * @param  the type of the response that is expected as a result of handling the
+ * request.
+ */
+public interface McpRequestHandler {
+
+	/**
+	 * Handles a request from the client.
+	 * @param exchange the exchange associated with the client that allows calling back to
+	 * the connected client or inspecting its capabilities.
+	 * @param params the parameters of the request.
+	 * @return a Mono that will emit the response to the request.
+	 */
+	Mono handle(McpAsyncServerExchange exchange, Object params);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
index d4b8addf4..f5dfffffb 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -21,6 +21,8 @@
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStatelessServerTransport;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
@@ -131,6 +133,8 @@
  */
 public interface McpServer {
 
+	McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("mcp-server", "1.0.0");
+
 	/**
 	 * Starts building a synchronous MCP server that provides blocking operations.
 	 * Synchronous servers block the current Thread's execution upon each request before
@@ -139,8 +143,8 @@ public interface McpServer {
 	 * @param transportProvider The transport layer implementation for MCP communication.
 	 * @return A new instance of {@link SyncSpecification} for configuring the server.
 	 */
-	static SyncSpecification sync(McpServerTransportProvider transportProvider) {
-		return new SyncSpecification(transportProvider);
+	static SingleSessionSyncSpecification sync(McpServerTransportProvider transportProvider) {
+		return new SingleSessionSyncSpecification(transportProvider);
 	}
 
 	/**
@@ -151,31 +155,129 @@ static SyncSpecification sync(McpServerTransportProvider transportProvider) {
 	 * @param transportProvider The transport layer implementation for MCP communication.
 	 * @return A new instance of {@link AsyncSpecification} for configuring the server.
 	 */
-	static AsyncSpecification async(McpServerTransportProvider transportProvider) {
-		return new AsyncSpecification(transportProvider);
+	static AsyncSpecification async(McpServerTransportProvider transportProvider) {
+		return new SingleSessionAsyncSpecification(transportProvider);
 	}
 
 	/**
-	 * Asynchronous server specification.
+	 * Starts building a synchronous MCP server that provides blocking operations.
+	 * Synchronous servers block the current Thread's execution upon each request before
+	 * giving the control back to the caller, making them simpler to implement but
+	 * potentially less scalable for concurrent operations.
+	 * @param transportProvider The transport layer implementation for MCP communication.
+	 * @return A new instance of {@link SyncSpecification} for configuring the server.
+	 */
+	static StreamableSyncSpecification sync(McpStreamableServerTransportProvider transportProvider) {
+		return new StreamableSyncSpecification(transportProvider);
+	}
+
+	/**
+	 * Starts building an asynchronous MCP server that provides non-blocking operations.
+	 * Asynchronous servers can handle multiple requests concurrently on a single Thread
+	 * using a functional paradigm with non-blocking server transports, making them more
+	 * scalable for high-concurrency scenarios but more complex to implement.
+	 * @param transportProvider The transport layer implementation for MCP communication.
+	 * @return A new instance of {@link AsyncSpecification} for configuring the server.
+	 */
+	static AsyncSpecification async(McpStreamableServerTransportProvider transportProvider) {
+		return new StreamableServerAsyncSpecification(transportProvider);
+	}
+
+	/**
+	 * Starts building an asynchronous MCP server that provides non-blocking operations.
+	 * Asynchronous servers can handle multiple requests concurrently on a single Thread
+	 * using a functional paradigm with non-blocking server transports, making them more
+	 * scalable for high-concurrency scenarios but more complex to implement.
+	 * @param transport The transport layer implementation for MCP communication.
+	 * @return A new instance of {@link AsyncSpecification} for configuring the server.
+	 */
+	static StatelessAsyncSpecification async(McpStatelessServerTransport transport) {
+		return new StatelessAsyncSpecification(transport);
+	}
+
+	/**
+	 * Starts building a synchronous MCP server that provides blocking operations.
+	 * Synchronous servers block the current Thread's execution upon each request before
+	 * giving the control back to the caller, making them simpler to implement but
+	 * potentially less scalable for concurrent operations.
+	 * @param transport The transport layer implementation for MCP communication.
+	 * @return A new instance of {@link SyncSpecification} for configuring the server.
 	 */
-	class AsyncSpecification {
+	static StatelessSyncSpecification sync(McpStatelessServerTransport transport) {
+		return new StatelessSyncSpecification(transport);
+	}
 
-		private static final McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("mcp-server",
-				"1.0.0");
+	class SingleSessionAsyncSpecification extends AsyncSpecification {
 
 		private final McpServerTransportProvider transportProvider;
 
-		private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+		private SingleSessionAsyncSpecification(McpServerTransportProvider transportProvider) {
+			Assert.notNull(transportProvider, "Transport provider must not be null");
+			this.transportProvider = transportProvider;
+		}
+
+		/**
+		 * Builds an asynchronous MCP server that provides non-blocking operations.
+		 * @return A new instance of {@link McpAsyncServer} configured with this builder's
+		 * settings.
+		 */
+		@Override
+		public McpAsyncServer build() {
+			var features = new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
+					this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers,
+					this.instructions);
+			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
+			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
+					: new DefaultJsonSchemaValidator(mapper);
+			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout,
+					this.uriTemplateManagerFactory, jsonSchemaValidator);
+		}
+
+	}
+
+	class StreamableServerAsyncSpecification extends AsyncSpecification {
+
+		private final McpStreamableServerTransportProvider transportProvider;
+
+		public StreamableServerAsyncSpecification(McpStreamableServerTransportProvider transportProvider) {
+			this.transportProvider = transportProvider;
+		}
+
+		/**
+		 * Builds an asynchronous MCP server that provides non-blocking operations.
+		 * @return A new instance of {@link McpAsyncServer} configured with this builder's
+		 * settings.
+		 */
+		@Override
+		public McpAsyncServer build() {
+			var features = new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
+					this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers,
+					this.instructions);
+			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
+			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
+					: new DefaultJsonSchemaValidator(mapper);
+			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout,
+					this.uriTemplateManagerFactory, jsonSchemaValidator);
+		}
+
+	}
+
+	/**
+	 * Asynchronous server specification.
+	 */
+	abstract class AsyncSpecification> {
+
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
-		private ObjectMapper objectMapper;
+		ObjectMapper objectMapper;
 
-		private McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
+		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
 
-		private McpSchema.ServerCapabilities serverCapabilities;
+		McpSchema.ServerCapabilities serverCapabilities;
 
-		private JsonSchemaValidator jsonSchemaValidator;
+		JsonSchemaValidator jsonSchemaValidator;
 
-		private String instructions;
+		String instructions;
 
 		/**
 		 * The Model Context Protocol (MCP) allows servers to expose tools that can be
@@ -184,7 +286,7 @@ class AsyncSpecification {
 		 * Each tool is uniquely identified by a name and includes metadata describing its
 		 * schema.
 		 */
-		private final List tools = new ArrayList<>();
+		final List tools = new ArrayList<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -193,9 +295,9 @@ class AsyncSpecification {
 		 * application-specific information. Each resource is uniquely identified by a
 		 * URI.
 		 */
-		private final Map resources = new HashMap<>();
+		final Map resources = new HashMap<>();
 
-		private final List resourceTemplates = new ArrayList<>();
+		final List resourceTemplates = new ArrayList<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -204,18 +306,15 @@ class AsyncSpecification {
 		 * discover available prompts, retrieve their contents, and provide arguments to
 		 * customize them.
 		 */
-		private final Map prompts = new HashMap<>();
+		final Map prompts = new HashMap<>();
 
-		private final Map completions = new HashMap<>();
+		final Map completions = new HashMap<>();
 
-		private final List, Mono>> rootsChangeHandlers = new ArrayList<>();
+		final List, Mono>> rootsChangeHandlers = new ArrayList<>();
 
-		private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
+		Duration requestTimeout = Duration.ofHours(10); // Default timeout
 
-		private AsyncSpecification(McpServerTransportProvider transportProvider) {
-			Assert.notNull(transportProvider, "Transport provider must not be null");
-			this.transportProvider = transportProvider;
-		}
+		public abstract McpAsyncServer build();
 
 		/**
 		 * Sets the URI template manager factory to use for creating URI templates. This
@@ -224,7 +323,7 @@ private AsyncSpecification(McpServerTransportProvider transportProvider) {
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if uriTemplateManagerFactory is null
 		 */
-		public AsyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory uriTemplateManagerFactory) {
+		public AsyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory uriTemplateManagerFactory) {
 			Assert.notNull(uriTemplateManagerFactory, "URI template manager factory must not be null");
 			this.uriTemplateManagerFactory = uriTemplateManagerFactory;
 			return this;
@@ -239,7 +338,7 @@ public AsyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if requestTimeout is null
 		 */
-		public AsyncSpecification requestTimeout(Duration requestTimeout) {
+		public AsyncSpecification requestTimeout(Duration requestTimeout) {
 			Assert.notNull(requestTimeout, "Request timeout must not be null");
 			this.requestTimeout = requestTimeout;
 			return this;
@@ -254,7 +353,7 @@ public AsyncSpecification requestTimeout(Duration requestTimeout) {
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if serverInfo is null
 		 */
-		public AsyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
+		public AsyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
 			Assert.notNull(serverInfo, "Server info must not be null");
 			this.serverInfo = serverInfo;
 			return this;
@@ -270,7 +369,7 @@ public AsyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
 		 * @throws IllegalArgumentException if name or version is null or empty
 		 * @see #serverInfo(McpSchema.Implementation)
 		 */
-		public AsyncSpecification serverInfo(String name, String version) {
+		public AsyncSpecification serverInfo(String name, String version) {
 			Assert.hasText(name, "Name must not be null or empty");
 			Assert.hasText(version, "Version must not be null or empty");
 			this.serverInfo = new McpSchema.Implementation(name, version);
@@ -284,7 +383,7 @@ public AsyncSpecification serverInfo(String name, String version) {
 		 * @param instructions The instructions text. Can be null or empty.
 		 * @return This builder instance for method chaining
 		 */
-		public AsyncSpecification instructions(String instructions) {
+		public AsyncSpecification instructions(String instructions) {
 			this.instructions = instructions;
 			return this;
 		}
@@ -303,7 +402,7 @@ public AsyncSpecification instructions(String instructions) {
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if serverCapabilities is null
 		 */
-		public AsyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+		public AsyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
 			Assert.notNull(serverCapabilities, "Server capabilities must not be null");
 			this.serverCapabilities = serverCapabilities;
 			return this;
@@ -334,7 +433,7 @@ public AsyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabi
 		 * calls that require a request object.
 		 */
 		@Deprecated
-		public AsyncSpecification tool(McpSchema.Tool tool,
+		public AsyncSpecification tool(McpSchema.Tool tool,
 				BiFunction, Mono> handler) {
 			Assert.notNull(tool, "Tool must not be null");
 			Assert.notNull(handler, "Handler must not be null");
@@ -358,7 +457,7 @@ public AsyncSpecification tool(McpSchema.Tool tool,
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if tool or handler is null
 		 */
-		public AsyncSpecification toolCall(McpSchema.Tool tool,
+		public AsyncSpecification toolCall(McpSchema.Tool tool,
 				BiFunction> callHandler) {
 
 			Assert.notNull(tool, "Tool must not be null");
@@ -381,7 +480,7 @@ public AsyncSpecification toolCall(McpSchema.Tool tool,
 		 * @throws IllegalArgumentException if toolSpecifications is null
 		 * @see #tools(McpServerFeatures.AsyncToolSpecification...)
 		 */
-		public AsyncSpecification tools(List toolSpecifications) {
+		public AsyncSpecification tools(List toolSpecifications) {
 			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
 
 			for (var tool : toolSpecifications) {
@@ -408,7 +507,7 @@ public AsyncSpecification tools(List t
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if toolSpecifications is null
 		 */
-		public AsyncSpecification tools(McpServerFeatures.AsyncToolSpecification... toolSpecifications) {
+		public AsyncSpecification tools(McpServerFeatures.AsyncToolSpecification... toolSpecifications) {
 			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
 
 			for (McpServerFeatures.AsyncToolSpecification tool : toolSpecifications) {
@@ -434,7 +533,7 @@ private void assertNoDuplicateTool(String toolName) {
 		 * @throws IllegalArgumentException if resourceSpecifications is null
 		 * @see #resources(McpServerFeatures.AsyncResourceSpecification...)
 		 */
-		public AsyncSpecification resources(
+		public AsyncSpecification resources(
 				Map resourceSpecifications) {
 			Assert.notNull(resourceSpecifications, "Resource handlers map must not be null");
 			this.resources.putAll(resourceSpecifications);
@@ -450,7 +549,8 @@ public AsyncSpecification resources(
 		 * @throws IllegalArgumentException if resourceSpecifications is null
 		 * @see #resources(McpServerFeatures.AsyncResourceSpecification...)
 		 */
-		public AsyncSpecification resources(List resourceSpecifications) {
+		public AsyncSpecification resources(
+				List resourceSpecifications) {
 			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
 			for (McpServerFeatures.AsyncResourceSpecification resource : resourceSpecifications) {
 				this.resources.put(resource.resource().uri(), resource);
@@ -475,7 +575,7 @@ public AsyncSpecification resources(List resources(McpServerFeatures.AsyncResourceSpecification... resourceSpecifications) {
 			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
 			for (McpServerFeatures.AsyncResourceSpecification resource : resourceSpecifications) {
 				this.resources.put(resource.resource().uri(), resource);
@@ -500,7 +600,7 @@ public AsyncSpecification resources(McpServerFeatures.AsyncResourceSpecification
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public AsyncSpecification resourceTemplates(List resourceTemplates) {
+		public AsyncSpecification resourceTemplates(List resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
 			this.resourceTemplates.addAll(resourceTemplates);
 			return this;
@@ -514,7 +614,7 @@ public AsyncSpecification resourceTemplates(List resourceTempl
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(List)
 		 */
-		public AsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public AsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
 			for (ResourceTemplate resourceTemplate : resourceTemplates) {
 				this.resourceTemplates.add(resourceTemplate);
@@ -539,7 +639,7 @@ public AsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplate
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if prompts is null
 		 */
-		public AsyncSpecification prompts(Map prompts) {
+		public AsyncSpecification prompts(Map prompts) {
 			Assert.notNull(prompts, "Prompts map must not be null");
 			this.prompts.putAll(prompts);
 			return this;
@@ -553,7 +653,7 @@ public AsyncSpecification prompts(Map prompts) {
+		public AsyncSpecification prompts(List prompts) {
 			Assert.notNull(prompts, "Prompts list must not be null");
 			for (McpServerFeatures.AsyncPromptSpecification prompt : prompts) {
 				this.prompts.put(prompt.prompt().name(), prompt);
@@ -577,7 +677,7 @@ public AsyncSpecification prompts(List prompts(McpServerFeatures.AsyncPromptSpecification... prompts) {
 			Assert.notNull(prompts, "Prompts list must not be null");
 			for (McpServerFeatures.AsyncPromptSpecification prompt : prompts) {
 				this.prompts.put(prompt.prompt().name(), prompt);
@@ -592,7 +692,7 @@ public AsyncSpecification prompts(McpServerFeatures.AsyncPromptSpecification...
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if completions is null
 		 */
-		public AsyncSpecification completions(List completions) {
+		public AsyncSpecification completions(List completions) {
 			Assert.notNull(completions, "Completions list must not be null");
 			for (McpServerFeatures.AsyncCompletionSpecification completion : completions) {
 				this.completions.put(completion.referenceKey(), completion);
@@ -607,7 +707,7 @@ public AsyncSpecification completions(List completions(McpServerFeatures.AsyncCompletionSpecification... completions) {
 			Assert.notNull(completions, "Completions list must not be null");
 			for (McpServerFeatures.AsyncCompletionSpecification completion : completions) {
 				this.completions.put(completion.referenceKey(), completion);
@@ -625,7 +725,7 @@ public AsyncSpecification completions(McpServerFeatures.AsyncCompletionSpecifica
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if consumer is null
 		 */
-		public AsyncSpecification rootsChangeHandler(
+		public AsyncSpecification rootsChangeHandler(
 				BiFunction, Mono> handler) {
 			Assert.notNull(handler, "Consumer must not be null");
 			this.rootsChangeHandlers.add(handler);
@@ -641,7 +741,7 @@ public AsyncSpecification rootsChangeHandler(
 		 * @throws IllegalArgumentException if consumers is null
 		 * @see #rootsChangeHandler(BiFunction)
 		 */
-		public AsyncSpecification rootsChangeHandlers(
+		public AsyncSpecification rootsChangeHandlers(
 				List, Mono>> handlers) {
 			Assert.notNull(handlers, "Handlers list must not be null");
 			this.rootsChangeHandlers.addAll(handlers);
@@ -657,7 +757,7 @@ public AsyncSpecification rootsChangeHandlers(
 		 * @throws IllegalArgumentException if consumers is null
 		 * @see #rootsChangeHandlers(List)
 		 */
-		public AsyncSpecification rootsChangeHandlers(
+		public AsyncSpecification rootsChangeHandlers(
 				@SuppressWarnings("unchecked") BiFunction, Mono>... handlers) {
 			Assert.notNull(handlers, "Handlers list must not be null");
 			return this.rootsChangeHandlers(Arrays.asList(handlers));
@@ -669,7 +769,7 @@ public AsyncSpecification rootsChangeHandlers(
 		 * @return This builder instance for method chaining.
 		 * @throws IllegalArgumentException if objectMapper is null
 		 */
-		public AsyncSpecification objectMapper(ObjectMapper objectMapper) {
+		public AsyncSpecification objectMapper(ObjectMapper objectMapper) {
 			Assert.notNull(objectMapper, "ObjectMapper must not be null");
 			this.objectMapper = objectMapper;
 			return this;
@@ -683,26 +783,76 @@ public AsyncSpecification objectMapper(ObjectMapper objectMapper) {
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if jsonSchemaValidator is null
 		 */
-		public AsyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+		public AsyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
 			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
 			this.jsonSchemaValidator = jsonSchemaValidator;
 			return this;
 		}
 
+	}
+
+	class SingleSessionSyncSpecification extends SyncSpecification {
+
+		private final McpServerTransportProvider transportProvider;
+
+		private SingleSessionSyncSpecification(McpServerTransportProvider transportProvider) {
+			Assert.notNull(transportProvider, "Transport provider must not be null");
+			this.transportProvider = transportProvider;
+		}
+
 		/**
-		 * Builds an asynchronous MCP server that provides non-blocking operations.
-		 * @return A new instance of {@link McpAsyncServer} configured with this builder's
+		 * Builds a synchronous MCP server that provides blocking operations.
+		 * @return A new instance of {@link McpSyncServer} configured with this builder's
 		 * settings.
 		 */
-		public McpAsyncServer build() {
-			var features = new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
-					this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers,
-					this.instructions);
+		@Override
+		public McpSyncServer build() {
+			McpServerFeatures.Sync syncFeatures = new McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities,
+					this.tools, this.resources, this.resourceTemplates, this.prompts, this.completions,
+					this.rootsChangeHandlers, this.instructions);
+			McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures,
+					this.immediateExecution);
 			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
 					: new DefaultJsonSchemaValidator(mapper);
-			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout,
+
+			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout,
+					this.uriTemplateManagerFactory, jsonSchemaValidator);
+
+			return new McpSyncServer(asyncServer, this.immediateExecution);
+		}
+
+	}
+
+	class StreamableSyncSpecification extends SyncSpecification {
+
+		private final McpStreamableServerTransportProvider transportProvider;
+
+		private StreamableSyncSpecification(McpStreamableServerTransportProvider transportProvider) {
+			Assert.notNull(transportProvider, "Transport provider must not be null");
+			this.transportProvider = transportProvider;
+		}
+
+		/**
+		 * Builds a synchronous MCP server that provides blocking operations.
+		 * @return A new instance of {@link McpSyncServer} configured with this builder's
+		 * settings.
+		 */
+		@Override
+		public McpSyncServer build() {
+			McpServerFeatures.Sync syncFeatures = new McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities,
+					this.tools, this.resources, this.resourceTemplates, this.prompts, this.completions,
+					this.rootsChangeHandlers, this.instructions);
+			McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures,
+					this.immediateExecution);
+			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
+			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
+					: new DefaultJsonSchemaValidator(mapper);
+
+			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout,
 					this.uriTemplateManagerFactory, jsonSchemaValidator);
+
+			return new McpSyncServer(asyncServer, this.immediateExecution);
 		}
 
 	}
@@ -710,22 +860,17 @@ public McpAsyncServer build() {
 	/**
 	 * Synchronous server specification.
 	 */
-	class SyncSpecification {
-
-		private static final McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("mcp-server",
-				"1.0.0");
-
-		private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+	abstract class SyncSpecification> {
 
-		private final McpServerTransportProvider transportProvider;
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
-		private ObjectMapper objectMapper;
+		ObjectMapper objectMapper;
 
-		private McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
+		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
 
-		private McpSchema.ServerCapabilities serverCapabilities;
+		McpSchema.ServerCapabilities serverCapabilities;
 
-		private String instructions;
+		String instructions;
 
 		/**
 		 * The Model Context Protocol (MCP) allows servers to expose tools that can be
@@ -734,7 +879,7 @@ class SyncSpecification {
 		 * Each tool is uniquely identified by a name and includes metadata describing its
 		 * schema.
 		 */
-		private final List tools = new ArrayList<>();
+		final List tools = new ArrayList<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -743,11 +888,11 @@ class SyncSpecification {
 		 * application-specific information. Each resource is uniquely identified by a
 		 * URI.
 		 */
-		private final Map resources = new HashMap<>();
+		final Map resources = new HashMap<>();
 
-		private final List resourceTemplates = new ArrayList<>();
+		final List resourceTemplates = new ArrayList<>();
 
-		private JsonSchemaValidator jsonSchemaValidator;
+		JsonSchemaValidator jsonSchemaValidator;
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -756,20 +901,17 @@ class SyncSpecification {
 		 * discover available prompts, retrieve their contents, and provide arguments to
 		 * customize them.
 		 */
-		private final Map prompts = new HashMap<>();
+		final Map prompts = new HashMap<>();
 
-		private final Map completions = new HashMap<>();
+		final Map completions = new HashMap<>();
 
-		private final List>> rootsChangeHandlers = new ArrayList<>();
+		final List>> rootsChangeHandlers = new ArrayList<>();
 
-		private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
+		Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
 
-		private boolean immediateExecution = false;
+		boolean immediateExecution = false;
 
-		private SyncSpecification(McpServerTransportProvider transportProvider) {
-			Assert.notNull(transportProvider, "Transport provider must not be null");
-			this.transportProvider = transportProvider;
-		}
+		public abstract McpSyncServer build();
 
 		/**
 		 * Sets the URI template manager factory to use for creating URI templates. This
@@ -778,7 +920,7 @@ private SyncSpecification(McpServerTransportProvider transportProvider) {
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if uriTemplateManagerFactory is null
 		 */
-		public SyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory uriTemplateManagerFactory) {
+		public SyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory uriTemplateManagerFactory) {
 			Assert.notNull(uriTemplateManagerFactory, "URI template manager factory must not be null");
 			this.uriTemplateManagerFactory = uriTemplateManagerFactory;
 			return this;
@@ -790,10 +932,10 @@ public SyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory
 		 * resource access, and prompt operations.
 		 * @param requestTimeout The duration to wait before timing out requests. Must not
 		 * be null.
-		 * @return This builder instance for method chaining
+		 * @return this builder instance for method chaining
 		 * @throws IllegalArgumentException if requestTimeout is null
 		 */
-		public SyncSpecification requestTimeout(Duration requestTimeout) {
+		public SyncSpecification requestTimeout(Duration requestTimeout) {
 			Assert.notNull(requestTimeout, "Request timeout must not be null");
 			this.requestTimeout = requestTimeout;
 			return this;
@@ -808,7 +950,7 @@ public SyncSpecification requestTimeout(Duration requestTimeout) {
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if serverInfo is null
 		 */
-		public SyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
+		public SyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
 			Assert.notNull(serverInfo, "Server info must not be null");
 			this.serverInfo = serverInfo;
 			return this;
@@ -824,7 +966,7 @@ public SyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
 		 * @throws IllegalArgumentException if name or version is null or empty
 		 * @see #serverInfo(McpSchema.Implementation)
 		 */
-		public SyncSpecification serverInfo(String name, String version) {
+		public SyncSpecification serverInfo(String name, String version) {
 			Assert.hasText(name, "Name must not be null or empty");
 			Assert.hasText(version, "Version must not be null or empty");
 			this.serverInfo = new McpSchema.Implementation(name, version);
@@ -838,7 +980,7 @@ public SyncSpecification serverInfo(String name, String version) {
 		 * @param instructions The instructions text. Can be null or empty.
 		 * @return This builder instance for method chaining
 		 */
-		public SyncSpecification instructions(String instructions) {
+		public SyncSpecification instructions(String instructions) {
 			this.instructions = instructions;
 			return this;
 		}
@@ -857,7 +999,7 @@ public SyncSpecification instructions(String instructions) {
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if serverCapabilities is null
 		 */
-		public SyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+		public SyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
 			Assert.notNull(serverCapabilities, "Server capabilities must not be null");
 			this.serverCapabilities = serverCapabilities;
 			return this;
@@ -887,7 +1029,7 @@ public SyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabil
 		 * calls that require a request object.
 		 */
 		@Deprecated
-		public SyncSpecification tool(McpSchema.Tool tool,
+		public SyncSpecification tool(McpSchema.Tool tool,
 				BiFunction, McpSchema.CallToolResult> handler) {
 			Assert.notNull(tool, "Tool must not be null");
 			Assert.notNull(handler, "Handler must not be null");
@@ -911,7 +1053,7 @@ public SyncSpecification tool(McpSchema.Tool tool,
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if tool or handler is null
 		 */
-		public SyncSpecification toolCall(McpSchema.Tool tool,
+		public SyncSpecification toolCall(McpSchema.Tool tool,
 				BiFunction handler) {
 			Assert.notNull(tool, "Tool must not be null");
 			Assert.notNull(handler, "Handler must not be null");
@@ -932,7 +1074,7 @@ public SyncSpecification toolCall(McpSchema.Tool tool,
 		 * @throws IllegalArgumentException if toolSpecifications is null
 		 * @see #tools(McpServerFeatures.SyncToolSpecification...)
 		 */
-		public SyncSpecification tools(List toolSpecifications) {
+		public SyncSpecification tools(List toolSpecifications) {
 			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
 
 			for (var tool : toolSpecifications) {
@@ -961,7 +1103,7 @@ public SyncSpecification tools(List too
 		 * @throws IllegalArgumentException if toolSpecifications is null
 		 * @see #tools(List)
 		 */
-		public SyncSpecification tools(McpServerFeatures.SyncToolSpecification... toolSpecifications) {
+		public SyncSpecification tools(McpServerFeatures.SyncToolSpecification... toolSpecifications) {
 			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
 
 			for (McpServerFeatures.SyncToolSpecification tool : toolSpecifications) {
@@ -987,7 +1129,7 @@ private void assertNoDuplicateTool(String toolName) {
 		 * @throws IllegalArgumentException if resourceSpecifications is null
 		 * @see #resources(McpServerFeatures.SyncResourceSpecification...)
 		 */
-		public SyncSpecification resources(
+		public SyncSpecification resources(
 				Map resourceSpecifications) {
 			Assert.notNull(resourceSpecifications, "Resource handlers map must not be null");
 			this.resources.putAll(resourceSpecifications);
@@ -1003,7 +1145,8 @@ public SyncSpecification resources(
 		 * @throws IllegalArgumentException if resourceSpecifications is null
 		 * @see #resources(McpServerFeatures.SyncResourceSpecification...)
 		 */
-		public SyncSpecification resources(List resourceSpecifications) {
+		public SyncSpecification resources(
+				List resourceSpecifications) {
 			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
 			for (McpServerFeatures.SyncResourceSpecification resource : resourceSpecifications) {
 				this.resources.put(resource.resource().uri(), resource);
@@ -1028,7 +1171,7 @@ public SyncSpecification resources(List resources(McpServerFeatures.SyncResourceSpecification... resourceSpecifications) {
 			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
 			for (McpServerFeatures.SyncResourceSpecification resource : resourceSpecifications) {
 				this.resources.put(resource.resource().uri(), resource);
@@ -1053,7 +1196,7 @@ public SyncSpecification resources(McpServerFeatures.SyncResourceSpecification..
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public SyncSpecification resourceTemplates(List resourceTemplates) {
+		public SyncSpecification resourceTemplates(List resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
 			this.resourceTemplates.addAll(resourceTemplates);
 			return this;
@@ -1067,7 +1210,7 @@ public SyncSpecification resourceTemplates(List resourceTempla
 		 * @throws IllegalArgumentException if resourceTemplates is null
 		 * @see #resourceTemplates(List)
 		 */
-		public SyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public SyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
 			for (ResourceTemplate resourceTemplate : resourceTemplates) {
 				this.resourceTemplates.add(resourceTemplate);
@@ -1093,7 +1236,7 @@ public SyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if prompts is null
 		 */
-		public SyncSpecification prompts(Map prompts) {
+		public SyncSpecification prompts(Map prompts) {
 			Assert.notNull(prompts, "Prompts map must not be null");
 			this.prompts.putAll(prompts);
 			return this;
@@ -1107,7 +1250,7 @@ public SyncSpecification prompts(Map prompts) {
+		public SyncSpecification prompts(List prompts) {
 			Assert.notNull(prompts, "Prompts list must not be null");
 			for (McpServerFeatures.SyncPromptSpecification prompt : prompts) {
 				this.prompts.put(prompt.prompt().name(), prompt);
@@ -1131,7 +1274,7 @@ public SyncSpecification prompts(List
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if prompts is null
 		 */
-		public SyncSpecification prompts(McpServerFeatures.SyncPromptSpecification... prompts) {
+		public SyncSpecification prompts(McpServerFeatures.SyncPromptSpecification... prompts) {
 			Assert.notNull(prompts, "Prompts list must not be null");
 			for (McpServerFeatures.SyncPromptSpecification prompt : prompts) {
 				this.prompts.put(prompt.prompt().name(), prompt);
@@ -1147,7 +1290,7 @@ public SyncSpecification prompts(McpServerFeatures.SyncPromptSpecification... pr
 		 * @throws IllegalArgumentException if completions is null
 		 * @see #completions(McpServerFeatures.SyncCompletionSpecification...)
 		 */
-		public SyncSpecification completions(List completions) {
+		public SyncSpecification completions(List completions) {
 			Assert.notNull(completions, "Completions list must not be null");
 			for (McpServerFeatures.SyncCompletionSpecification completion : completions) {
 				this.completions.put(completion.referenceKey(), completion);
@@ -1162,7 +1305,7 @@ public SyncSpecification completions(List completions(McpServerFeatures.SyncCompletionSpecification... completions) {
 			Assert.notNull(completions, "Completions list must not be null");
 			for (McpServerFeatures.SyncCompletionSpecification completion : completions) {
 				this.completions.put(completion.referenceKey(), completion);
@@ -1180,7 +1323,8 @@ public SyncSpecification completions(McpServerFeatures.SyncCompletionSpecificati
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if consumer is null
 		 */
-		public SyncSpecification rootsChangeHandler(BiConsumer> handler) {
+		public SyncSpecification rootsChangeHandler(
+				BiConsumer> handler) {
 			Assert.notNull(handler, "Consumer must not be null");
 			this.rootsChangeHandlers.add(handler);
 			return this;
@@ -1195,7 +1339,7 @@ public SyncSpecification rootsChangeHandler(BiConsumer rootsChangeHandlers(
 				List>> handlers) {
 			Assert.notNull(handlers, "Handlers list must not be null");
 			this.rootsChangeHandlers.addAll(handlers);
@@ -1211,7 +1355,7 @@ public SyncSpecification rootsChangeHandlers(
 		 * @throws IllegalArgumentException if consumers is null
 		 * @see #rootsChangeHandlers(List)
 		 */
-		public SyncSpecification rootsChangeHandlers(
+		public SyncSpecification rootsChangeHandlers(
 				BiConsumer>... handlers) {
 			Assert.notNull(handlers, "Handlers list must not be null");
 			return this.rootsChangeHandlers(List.of(handlers));
@@ -1223,13 +1367,13 @@ public SyncSpecification rootsChangeHandlers(
 		 * @return This builder instance for method chaining.
 		 * @throws IllegalArgumentException if objectMapper is null
 		 */
-		public SyncSpecification objectMapper(ObjectMapper objectMapper) {
+		public SyncSpecification objectMapper(ObjectMapper objectMapper) {
 			Assert.notNull(objectMapper, "ObjectMapper must not be null");
 			this.objectMapper = objectMapper;
 			return this;
 		}
 
-		public SyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+		public SyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
 			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
 			this.jsonSchemaValidator = jsonSchemaValidator;
 			return this;
@@ -1246,30 +1390,966 @@ public SyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValid
 		 * @return This builder instance for method chaining.
 		 *
 		 */
-		public SyncSpecification immediateExecution(boolean immediateExecution) {
+		public SyncSpecification immediateExecution(boolean immediateExecution) {
 			this.immediateExecution = immediateExecution;
 			return this;
 		}
 
+	}
+
+	class StatelessAsyncSpecification {
+
+		private final McpStatelessServerTransport transport;
+
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+
+		ObjectMapper objectMapper;
+
+		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
+
+		McpSchema.ServerCapabilities serverCapabilities;
+
+		JsonSchemaValidator jsonSchemaValidator;
+
+		String instructions;
+
 		/**
-		 * Builds a synchronous MCP server that provides blocking operations.
-		 * @return A new instance of {@link McpSyncServer} configured with this builder's
-		 * settings.
+		 * The Model Context Protocol (MCP) allows servers to expose tools that can be
+		 * invoked by language models. Tools enable models to interact with external
+		 * systems, such as querying databases, calling APIs, or performing computations.
+		 * Each tool is uniquely identified by a name and includes metadata describing its
+		 * schema.
 		 */
-		public McpSyncServer build() {
-			McpServerFeatures.Sync syncFeatures = new McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities,
-					this.tools, this.resources, this.resourceTemplates, this.prompts, this.completions,
-					this.rootsChangeHandlers, this.instructions);
-			McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures,
-					this.immediateExecution);
-			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
-			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
-					: new DefaultJsonSchemaValidator(mapper);
+		final List tools = new ArrayList<>();
 
-			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resources to clients. Resources allow servers to share data that
+		 * provides context to language models, such as files, database schemas, or
+		 * application-specific information. Each resource is uniquely identified by a
+		 * URI.
+		 */
+		final Map resources = new HashMap<>();
 
-			return new McpSyncServer(asyncServer, this.immediateExecution);
+		final List resourceTemplates = new ArrayList<>();
+
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose prompt templates to clients. Prompts allow servers to provide structured
+		 * messages and instructions for interacting with language models. Clients can
+		 * discover available prompts, retrieve their contents, and provide arguments to
+		 * customize them.
+		 */
+		final Map prompts = new HashMap<>();
+
+		final Map completions = new HashMap<>();
+
+		Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
+
+		public StatelessAsyncSpecification(McpStatelessServerTransport transport) {
+			this.transport = transport;
+		}
+
+		/**
+		 * Sets the URI template manager factory to use for creating URI templates. This
+		 * allows for custom URI template parsing and variable extraction.
+		 * @param uriTemplateManagerFactory The factory to use. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if uriTemplateManagerFactory is null
+		 */
+		public StatelessAsyncSpecification uriTemplateManagerFactory(
+				McpUriTemplateManagerFactory uriTemplateManagerFactory) {
+			Assert.notNull(uriTemplateManagerFactory, "URI template manager factory must not be null");
+			this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+			return this;
+		}
+
+		/**
+		 * Sets the duration to wait for server responses before timing out requests. This
+		 * timeout applies to all requests made through the client, including tool calls,
+		 * resource access, and prompt operations.
+		 * @param requestTimeout The duration to wait before timing out requests. Must not
+		 * be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if requestTimeout is null
+		 */
+		public StatelessAsyncSpecification requestTimeout(Duration requestTimeout) {
+			Assert.notNull(requestTimeout, "Request timeout must not be null");
+			this.requestTimeout = requestTimeout;
+			return this;
+		}
+
+		/**
+		 * Sets the server implementation information that will be shared with clients
+		 * during connection initialization. This helps with version compatibility,
+		 * debugging, and server identification.
+		 * @param serverInfo The server implementation details including name and version.
+		 * Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if serverInfo is null
+		 */
+		public StatelessAsyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
+			Assert.notNull(serverInfo, "Server info must not be null");
+			this.serverInfo = serverInfo;
+			return this;
+		}
+
+		/**
+		 * Sets the server implementation information using name and version strings. This
+		 * is a convenience method alternative to
+		 * {@link #serverInfo(McpSchema.Implementation)}.
+		 * @param name The server name. Must not be null or empty.
+		 * @param version The server version. Must not be null or empty.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if name or version is null or empty
+		 * @see #serverInfo(McpSchema.Implementation)
+		 */
+		public StatelessAsyncSpecification serverInfo(String name, String version) {
+			Assert.hasText(name, "Name must not be null or empty");
+			Assert.hasText(version, "Version must not be null or empty");
+			this.serverInfo = new McpSchema.Implementation(name, version);
+			return this;
+		}
+
+		/**
+		 * Sets the server instructions that will be shared with clients during connection
+		 * initialization. These instructions provide guidance to the client on how to
+		 * interact with this server.
+		 * @param instructions The instructions text. Can be null or empty.
+		 * @return This builder instance for method chaining
+		 */
+		public StatelessAsyncSpecification instructions(String instructions) {
+			this.instructions = instructions;
+			return this;
+		}
+
+		/**
+		 * Sets the server capabilities that will be advertised to clients during
+		 * connection initialization. Capabilities define what features the server
+		 * supports, such as:
+		 * 
    
+		 * 
  • Tool execution
+		 * 
  • Resource access
+		 * 
  • Prompt handling
+		 * 

+		 * @param serverCapabilities The server capabilities configuration. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if serverCapabilities is null
+		 */
+		public StatelessAsyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+			Assert.notNull(serverCapabilities, "Server capabilities must not be null");
+			this.serverCapabilities = serverCapabilities;
+			return this;
+		}
+
+		/**
+		 * Adds a single tool with its implementation handler to the server. This is a
+		 * convenience method for registering individual tools without creating a
+		 * {@link McpServerFeatures.AsyncToolSpecification} explicitly.
+		 * @param tool The tool definition including name, description, and schema. Must
+		 * not be null.
+		 * @param callHandler The function that implements the tool's logic. Must not be
+		 * null. The function's first argument is an {@link McpAsyncServerExchange} upon
+		 * which the server can interact with the connected client. The second argument is
+		 * the {@link McpSchema.CallToolRequest} object containing the tool call
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if tool or handler is null
+		 */
+		public StatelessAsyncSpecification toolCall(McpSchema.Tool tool,
+				BiFunction> callHandler) {
+
+			Assert.notNull(tool, "Tool must not be null");
+			Assert.notNull(callHandler, "Handler must not be null");
+			assertNoDuplicateTool(tool.name());
+
+			this.tools.add(new McpStatelessServerFeatures.AsyncToolSpecification(tool, callHandler));
+
+			return this;
+		}
+
+		/**
+		 * Adds multiple tools with their handlers to the server using a List. This method
+		 * is useful when tools are dynamically generated or loaded from a configuration
+		 * source.
+		 * @param toolSpecifications The list of tool specifications to add. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if toolSpecifications is null
+		 * @see #tools(McpStatelessServerFeatures.AsyncToolSpecification...)
+		 */
+		public StatelessAsyncSpecification tools(
+				List toolSpecifications) {
+			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+
+			for (var tool : toolSpecifications) {
+				assertNoDuplicateTool(tool.tool().name());
+				this.tools.add(tool);
+			}
+
+			return this;
+		}
+
+		/**
+		 * Adds multiple tools with their handlers to the server using varargs. This
+		 * method provides a convenient way to register multiple tools inline.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .tools(
+		 *     McpServerFeatures.AsyncToolSpecification.builder().tool(calculatorTool).callTool(calculatorHandler).build(),
+		 *     McpServerFeatures.AsyncToolSpecification.builder().tool(weatherTool).callTool(weatherHandler).build(),
+		 *     McpServerFeatures.AsyncToolSpecification.builder().tool(fileManagerTool).callTool(fileManagerHandler).build()
+		 * )
+		 * }

+		 * @param toolSpecifications The tool specifications to add. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if toolSpecifications is null
+		 */
+		public StatelessAsyncSpecification tools(
+				McpStatelessServerFeatures.AsyncToolSpecification... toolSpecifications) {
+			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+
+			for (var tool : toolSpecifications) {
+				assertNoDuplicateTool(tool.tool().name());
+				this.tools.add(tool);
+			}
+			return this;
+		}
+
+		private void assertNoDuplicateTool(String toolName) {
+			if (this.tools.stream().anyMatch(toolSpec -> toolSpec.tool().name().equals(toolName))) {
+				throw new IllegalArgumentException("Tool with name '" + toolName + "' is already registered.");
+			}
+		}
+
+		/**
+		 * Registers multiple resources with their handlers using a Map. This method is
+		 * useful when resources are dynamically generated or loaded from a configuration
+		 * source.
+		 * @param resourceSpecifications Map of resource name to specification. Must not
+		 * be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceSpecifications is null
+		 * @see #resources(McpStatelessServerFeatures.AsyncResourceSpecification...)
+		 */
+		public StatelessAsyncSpecification resources(
+				Map resourceSpecifications) {
+			Assert.notNull(resourceSpecifications, "Resource handlers map must not be null");
+			this.resources.putAll(resourceSpecifications);
+			return this;
+		}
+
+		/**
+		 * Registers multiple resources with their handlers using a List. This method is
+		 * useful when resources need to be added in bulk from a collection.
+		 * @param resourceSpecifications List of resource specifications. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceSpecifications is null
+		 * @see #resources(McpStatelessServerFeatures.AsyncResourceSpecification...)
+		 */
+		public StatelessAsyncSpecification resources(
+				List resourceSpecifications) {
+			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+			for (var resource : resourceSpecifications) {
+				this.resources.put(resource.resource().uri(), resource);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple resources with their handlers using varargs. This method
+		 * provides a convenient way to register multiple resources inline.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .resources(
+		 *     new McpServerFeatures.AsyncResourceSpecification(fileResource, fileHandler),
+		 *     new McpServerFeatures.AsyncResourceSpecification(dbResource, dbHandler),
+		 *     new McpServerFeatures.AsyncResourceSpecification(apiResource, apiHandler)
+		 * )
+		 * }

+		 * @param resourceSpecifications The resource specifications to add. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceSpecifications is null
+		 */
+		public StatelessAsyncSpecification resources(
+				McpStatelessServerFeatures.AsyncResourceSpecification... resourceSpecifications) {
+			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+			for (var resource : resourceSpecifications) {
+				this.resources.put(resource.resource().uri(), resource);
+			}
+			return this;
+		}
+
+		/**
+		 * Sets the resource templates that define patterns for dynamic resource access.
+		 * Templates use URI patterns with placeholders that can be filled at runtime.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .resourceTemplates(
+		 *     new ResourceTemplate("file://{path}", "Access files by path"),
+		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
+		 * )
+		 * }

+		 * @param resourceTemplates List of resource templates. If null, clears existing
+		 * templates.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceTemplates is null.
+		 * @see #resourceTemplates(ResourceTemplate...)
+		 */
+		public StatelessAsyncSpecification resourceTemplates(List resourceTemplates) {
+			Assert.notNull(resourceTemplates, "Resource templates must not be null");
+			this.resourceTemplates.addAll(resourceTemplates);
+			return this;
+		}
+
+		/**
+		 * Sets the resource templates using varargs for convenience. This is an
+		 * alternative to {@link #resourceTemplates(List)}.
+		 * @param resourceTemplates The resource templates to set.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceTemplates is null.
+		 * @see #resourceTemplates(List)
+		 */
+		public StatelessAsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+			Assert.notNull(resourceTemplates, "Resource templates must not be null");
+			for (ResourceTemplate resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.add(resourceTemplate);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple prompts with their handlers using a Map. This method is
+		 * useful when prompts are dynamically generated or loaded from a configuration
+		 * source.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .prompts(Map.of("analysis", new McpServerFeatures.AsyncPromptSpecification(
+		 *     new Prompt("analysis", "Code analysis template"),
+		 *     request -> Mono.fromSupplier(() -> generateAnalysisPrompt(request))
+		 *         .map(GetPromptResult::new)
+		 * )));
+		 * }

+		 * @param prompts Map of prompt name to specification. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if prompts is null
+		 */
+		public StatelessAsyncSpecification prompts(
+				Map prompts) {
+			Assert.notNull(prompts, "Prompts map must not be null");
+			this.prompts.putAll(prompts);
+			return this;
+		}
+
+		/**
+		 * Registers multiple prompts with their handlers using a List. This method is
+		 * useful when prompts need to be added in bulk from a collection.
+		 * @param prompts List of prompt specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if prompts is null
+		 * @see #prompts(McpStatelessServerFeatures.AsyncPromptSpecification...)
+		 */
+		public StatelessAsyncSpecification prompts(List prompts) {
+			Assert.notNull(prompts, "Prompts list must not be null");
+			for (var prompt : prompts) {
+				this.prompts.put(prompt.prompt().name(), prompt);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple prompts with their handlers using varargs. This method
+		 * provides a convenient way to register multiple prompts inline.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .prompts(
+		 *     new McpServerFeatures.AsyncPromptSpecification(analysisPrompt, analysisHandler),
+		 *     new McpServerFeatures.AsyncPromptSpecification(summaryPrompt, summaryHandler),
+		 *     new McpServerFeatures.AsyncPromptSpecification(reviewPrompt, reviewHandler)
+		 * )
+		 * }

+		 * @param prompts The prompt specifications to add. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if prompts is null
+		 */
+		public StatelessAsyncSpecification prompts(McpStatelessServerFeatures.AsyncPromptSpecification... prompts) {
+			Assert.notNull(prompts, "Prompts list must not be null");
+			for (var prompt : prompts) {
+				this.prompts.put(prompt.prompt().name(), prompt);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple completions with their handlers using a List. This method is
+		 * useful when completions need to be added in bulk from a collection.
+		 * @param completions List of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 */
+		public StatelessAsyncSpecification completions(
+				List completions) {
+			Assert.notNull(completions, "Completions list must not be null");
+			for (var completion : completions) {
+				this.completions.put(completion.referenceKey(), completion);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple completions with their handlers using varargs. This method
+		 * is useful when completions are defined inline and added directly.
+		 * @param completions Array of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 */
+		public StatelessAsyncSpecification completions(
+				McpStatelessServerFeatures.AsyncCompletionSpecification... completions) {
+			Assert.notNull(completions, "Completions list must not be null");
+			for (var completion : completions) {
+				this.completions.put(completion.referenceKey(), completion);
+			}
+			return this;
+		}
+
+		/**
+		 * Sets the object mapper to use for serializing and deserializing JSON messages.
+		 * @param objectMapper the instance to use. Must not be null.
+		 * @return This builder instance for method chaining.
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public StatelessAsyncSpecification objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the JSON schema validator to use for validating tool and resource schemas.
+		 * This ensures that the server's tools and resources conform to the expected
+		 * schema definitions.
+		 * @param jsonSchemaValidator The validator to use. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if jsonSchemaValidator is null
+		 */
+		public StatelessAsyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			this.jsonSchemaValidator = jsonSchemaValidator;
+			return this;
+		}
+
+		public McpStatelessAsyncServer build() {
+			var features = new McpStatelessServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
+					this.resources, this.resourceTemplates, this.prompts, this.completions, this.instructions);
+			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
+			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
+					: new DefaultJsonSchemaValidator(mapper);
+			return new McpStatelessAsyncServer(this.transport, mapper, features, this.requestTimeout,
+					this.uriTemplateManagerFactory, jsonSchemaValidator);
+		}
+
+	}
+
+	class StatelessSyncSpecification {
+
+		private final McpStatelessServerTransport transport;
+
+		boolean immediateExecution = false;
+
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+
+		ObjectMapper objectMapper;
+
+		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
+
+		McpSchema.ServerCapabilities serverCapabilities;
+
+		JsonSchemaValidator jsonSchemaValidator;
+
+		String instructions;
+
+		/**
+		 * The Model Context Protocol (MCP) allows servers to expose tools that can be
+		 * invoked by language models. Tools enable models to interact with external
+		 * systems, such as querying databases, calling APIs, or performing computations.
+		 * Each tool is uniquely identified by a name and includes metadata describing its
+		 * schema.
+		 */
+		final List tools = new ArrayList<>();
+
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resources to clients. Resources allow servers to share data that
+		 * provides context to language models, such as files, database schemas, or
+		 * application-specific information. Each resource is uniquely identified by a
+		 * URI.
+		 */
+		final Map resources = new HashMap<>();
+
+		final List resourceTemplates = new ArrayList<>();
+
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose prompt templates to clients. Prompts allow servers to provide structured
+		 * messages and instructions for interacting with language models. Clients can
+		 * discover available prompts, retrieve their contents, and provide arguments to
+		 * customize them.
+		 */
+		final Map prompts = new HashMap<>();
+
+		final Map completions = new HashMap<>();
+
+		Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
+
+		public StatelessSyncSpecification(McpStatelessServerTransport transport) {
+			this.transport = transport;
+		}
+
+		/**
+		 * Sets the URI template manager factory to use for creating URI templates. This
+		 * allows for custom URI template parsing and variable extraction.
+		 * @param uriTemplateManagerFactory The factory to use. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if uriTemplateManagerFactory is null
+		 */
+		public StatelessSyncSpecification uriTemplateManagerFactory(
+				McpUriTemplateManagerFactory uriTemplateManagerFactory) {
+			Assert.notNull(uriTemplateManagerFactory, "URI template manager factory must not be null");
+			this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+			return this;
+		}
+
+		/**
+		 * Sets the duration to wait for server responses before timing out requests. This
+		 * timeout applies to all requests made through the client, including tool calls,
+		 * resource access, and prompt operations.
+		 * @param requestTimeout The duration to wait before timing out requests. Must not
+		 * be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if requestTimeout is null
+		 */
+		public StatelessSyncSpecification requestTimeout(Duration requestTimeout) {
+			Assert.notNull(requestTimeout, "Request timeout must not be null");
+			this.requestTimeout = requestTimeout;
+			return this;
+		}
+
+		/**
+		 * Sets the server implementation information that will be shared with clients
+		 * during connection initialization. This helps with version compatibility,
+		 * debugging, and server identification.
+		 * @param serverInfo The server implementation details including name and version.
+		 * Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if serverInfo is null
+		 */
+		public StatelessSyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
+			Assert.notNull(serverInfo, "Server info must not be null");
+			this.serverInfo = serverInfo;
+			return this;
+		}
+
+		/**
+		 * Sets the server implementation information using name and version strings. This
+		 * is a convenience method alternative to
+		 * {@link #serverInfo(McpSchema.Implementation)}.
+		 * @param name The server name. Must not be null or empty.
+		 * @param version The server version. Must not be null or empty.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if name or version is null or empty
+		 * @see #serverInfo(McpSchema.Implementation)
+		 */
+		public StatelessSyncSpecification serverInfo(String name, String version) {
+			Assert.hasText(name, "Name must not be null or empty");
+			Assert.hasText(version, "Version must not be null or empty");
+			this.serverInfo = new McpSchema.Implementation(name, version);
+			return this;
+		}
+
+		/**
+		 * Sets the server instructions that will be shared with clients during connection
+		 * initialization. These instructions provide guidance to the client on how to
+		 * interact with this server.
+		 * @param instructions The instructions text. Can be null or empty.
+		 * @return This builder instance for method chaining
+		 */
+		public StatelessSyncSpecification instructions(String instructions) {
+			this.instructions = instructions;
+			return this;
+		}
+
+		/**
+		 * Sets the server capabilities that will be advertised to clients during
+		 * connection initialization. Capabilities define what features the server
+		 * supports, such as:
+		 * 
    
+		 * 
  • Tool execution
+		 * 
  • Resource access
+		 * 
  • Prompt handling
+		 * 

+		 * @param serverCapabilities The server capabilities configuration. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if serverCapabilities is null
+		 */
+		public StatelessSyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+			Assert.notNull(serverCapabilities, "Server capabilities must not be null");
+			this.serverCapabilities = serverCapabilities;
+			return this;
+		}
+
+		/**
+		 * Adds a single tool with its implementation handler to the server. This is a
+		 * convenience method for registering individual tools without creating a
+		 * {@link McpServerFeatures.SyncToolSpecification} explicitly.
+		 * @param tool The tool definition including name, description, and schema. Must
+		 * not be null.
+		 * @param callHandler The function that implements the tool's logic. Must not be
+		 * null. The function's first argument is an {@link McpSyncServerExchange} upon
+		 * which the server can interact with the connected client. The second argument is
+		 * the {@link McpSchema.CallToolRequest} object containing the tool call
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if tool or handler is null
+		 */
+		public StatelessSyncSpecification toolCall(McpSchema.Tool tool,
+				BiFunction callHandler) {
+
+			Assert.notNull(tool, "Tool must not be null");
+			Assert.notNull(callHandler, "Handler must not be null");
+			assertNoDuplicateTool(tool.name());
+
+			this.tools.add(new McpStatelessServerFeatures.SyncToolSpecification(tool, callHandler));
+
+			return this;
+		}
+
+		/**
+		 * Adds multiple tools with their handlers to the server using a List. This method
+		 * is useful when tools are dynamically generated or loaded from a configuration
+		 * source.
+		 * @param toolSpecifications The list of tool specifications to add. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if toolSpecifications is null
+		 * @see #tools(McpStatelessServerFeatures.SyncToolSpecification...)
+		 */
+		public StatelessSyncSpecification tools(
+				List toolSpecifications) {
+			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+
+			for (var tool : toolSpecifications) {
+				assertNoDuplicateTool(tool.tool().name());
+				this.tools.add(tool);
+			}
+
+			return this;
+		}
+
+		/**
+		 * Adds multiple tools with their handlers to the server using varargs. This
+		 * method provides a convenient way to register multiple tools inline.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .tools(
+		 *     McpServerFeatures.SyncToolSpecification.builder().tool(calculatorTool).callTool(calculatorHandler).build(),
+		 *     McpServerFeatures.SyncToolSpecification.builder().tool(weatherTool).callTool(weatherHandler).build(),
+		 *     McpServerFeatures.SyncToolSpecification.builder().tool(fileManagerTool).callTool(fileManagerHandler).build()
+		 * )
+		 * }

+		 * @param toolSpecifications The tool specifications to add. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if toolSpecifications is null
+		 */
+		public StatelessSyncSpecification tools(
+				McpStatelessServerFeatures.SyncToolSpecification... toolSpecifications) {
+			Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+
+			for (var tool : toolSpecifications) {
+				assertNoDuplicateTool(tool.tool().name());
+				this.tools.add(tool);
+			}
+			return this;
+		}
+
+		private void assertNoDuplicateTool(String toolName) {
+			if (this.tools.stream().anyMatch(toolSpec -> toolSpec.tool().name().equals(toolName))) {
+				throw new IllegalArgumentException("Tool with name '" + toolName + "' is already registered.");
+			}
+		}
+
+		/**
+		 * Registers multiple resources with their handlers using a Map. This method is
+		 * useful when resources are dynamically generated or loaded from a configuration
+		 * source.
+		 * @param resourceSpecifications Map of resource name to specification. Must not
+		 * be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceSpecifications is null
+		 * @see #resources(McpStatelessServerFeatures.SyncResourceSpecification...)
+		 */
+		public StatelessSyncSpecification resources(
+				Map resourceSpecifications) {
+			Assert.notNull(resourceSpecifications, "Resource handlers map must not be null");
+			this.resources.putAll(resourceSpecifications);
+			return this;
+		}
+
+		/**
+		 * Registers multiple resources with their handlers using a List. This method is
+		 * useful when resources need to be added in bulk from a collection.
+		 * @param resourceSpecifications List of resource specifications. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceSpecifications is null
+		 * @see #resources(McpStatelessServerFeatures.SyncResourceSpecification...)
+		 */
+		public StatelessSyncSpecification resources(
+				List resourceSpecifications) {
+			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+			for (var resource : resourceSpecifications) {
+				this.resources.put(resource.resource().uri(), resource);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple resources with their handlers using varargs. This method
+		 * provides a convenient way to register multiple resources inline.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .resources(
+		 *     new McpServerFeatures.SyncResourceSpecification(fileResource, fileHandler),
+		 *     new McpServerFeatures.SyncResourceSpecification(dbResource, dbHandler),
+		 *     new McpServerFeatures.SyncResourceSpecification(apiResource, apiHandler)
+		 * )
+		 * }

+		 * @param resourceSpecifications The resource specifications to add. Must not be
+		 * null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceSpecifications is null
+		 */
+		public StatelessSyncSpecification resources(
+				McpStatelessServerFeatures.SyncResourceSpecification... resourceSpecifications) {
+			Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+			for (var resource : resourceSpecifications) {
+				this.resources.put(resource.resource().uri(), resource);
+			}
+			return this;
+		}
+
+		/**
+		 * Sets the resource templates that define patterns for dynamic resource access.
+		 * Templates use URI patterns with placeholders that can be filled at runtime.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .resourceTemplates(
+		 *     new ResourceTemplate("file://{path}", "Access files by path"),
+		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
+		 * )
+		 * }

+		 * @param resourceTemplates List of resource templates. If null, clears existing
+		 * templates.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceTemplates is null.
+		 * @see #resourceTemplates(ResourceTemplate...)
+		 */
+		public StatelessSyncSpecification resourceTemplates(List resourceTemplates) {
+			Assert.notNull(resourceTemplates, "Resource templates must not be null");
+			this.resourceTemplates.addAll(resourceTemplates);
+			return this;
+		}
+
+		/**
+		 * Sets the resource templates using varargs for convenience. This is an
+		 * alternative to {@link #resourceTemplates(List)}.
+		 * @param resourceTemplates The resource templates to set.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if resourceTemplates is null.
+		 * @see #resourceTemplates(List)
+		 */
+		public StatelessSyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+			Assert.notNull(resourceTemplates, "Resource templates must not be null");
+			for (ResourceTemplate resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.add(resourceTemplate);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple prompts with their handlers using a Map. This method is
+		 * useful when prompts are dynamically generated or loaded from a configuration
+		 * source.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .prompts(Map.of("analysis", new McpServerFeatures.SyncPromptSpecification(
+		 *     new Prompt("analysis", "Code analysis template"),
+		 *     request -> Mono.fromSupplier(() -> generateAnalysisPrompt(request))
+		 *         .map(GetPromptResult::new)
+		 * )));
+		 * }

+		 * @param prompts Map of prompt name to specification. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if prompts is null
+		 */
+		public StatelessSyncSpecification prompts(
+				Map prompts) {
+			Assert.notNull(prompts, "Prompts map must not be null");
+			this.prompts.putAll(prompts);
+			return this;
+		}
+
+		/**
+		 * Registers multiple prompts with their handlers using a List. This method is
+		 * useful when prompts need to be added in bulk from a collection.
+		 * @param prompts List of prompt specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if prompts is null
+		 * @see #prompts(McpStatelessServerFeatures.SyncPromptSpecification...)
+		 */
+		public StatelessSyncSpecification prompts(List prompts) {
+			Assert.notNull(prompts, "Prompts list must not be null");
+			for (var prompt : prompts) {
+				this.prompts.put(prompt.prompt().name(), prompt);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple prompts with their handlers using varargs. This method
+		 * provides a convenient way to register multiple prompts inline.
+		 *
+		 * 

+		 * Example usage: 
{@code
+		 * .prompts(
+		 *     new McpServerFeatures.SyncPromptSpecification(analysisPrompt, analysisHandler),
+		 *     new McpServerFeatures.SyncPromptSpecification(summaryPrompt, summaryHandler),
+		 *     new McpServerFeatures.SyncPromptSpecification(reviewPrompt, reviewHandler)
+		 * )
+		 * }

+		 * @param prompts The prompt specifications to add. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if prompts is null
+		 */
+		public StatelessSyncSpecification prompts(McpStatelessServerFeatures.SyncPromptSpecification... prompts) {
+			Assert.notNull(prompts, "Prompts list must not be null");
+			for (var prompt : prompts) {
+				this.prompts.put(prompt.prompt().name(), prompt);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple completions with their handlers using a List. This method is
+		 * useful when completions need to be added in bulk from a collection.
+		 * @param completions List of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 */
+		public StatelessSyncSpecification completions(
+				List completions) {
+			Assert.notNull(completions, "Completions list must not be null");
+			for (var completion : completions) {
+				this.completions.put(completion.referenceKey(), completion);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple completions with their handlers using varargs. This method
+		 * is useful when completions are defined inline and added directly.
+		 * @param completions Array of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 */
+		public StatelessSyncSpecification completions(
+				McpStatelessServerFeatures.SyncCompletionSpecification... completions) {
+			Assert.notNull(completions, "Completions list must not be null");
+			for (var completion : completions) {
+				this.completions.put(completion.referenceKey(), completion);
+			}
+			return this;
+		}
+
+		/**
+		 * Sets the object mapper to use for serializing and deserializing JSON messages.
+		 * @param objectMapper the instance to use. Must not be null.
+		 * @return This builder instance for method chaining.
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public StatelessSyncSpecification objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the JSON schema validator to use for validating tool and resource schemas.
+		 * This ensures that the server's tools and resources conform to the expected
+		 * schema definitions.
+		 * @param jsonSchemaValidator The validator to use. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if jsonSchemaValidator is null
+		 */
+		public StatelessSyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			this.jsonSchemaValidator = jsonSchemaValidator;
+			return this;
+		}
+
+		/**
+		 * Enable on "immediate execution" of the operations on the underlying
+		 * {@link McpStatelessAsyncServer}. Defaults to false, which does blocking code
+		 * offloading to prevent accidental blocking of the non-blocking transport.
+		 * 

+		 * Do NOT set to true if the underlying transport is a non-blocking
+		 * implementation.
+		 * @param immediateExecution When true, do not offload work asynchronously.
+		 * @return This builder instance for method chaining.
+		 *
+		 */
+		public StatelessSyncSpecification immediateExecution(boolean immediateExecution) {
+			this.immediateExecution = immediateExecution;
+			return this;
+		}
+
+		public McpStatelessSyncServer build() {
+			/*
+			 * McpServerFeatures.Sync syncFeatures = new
+			 * McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities,
+			 * this.tools, this.resources, this.resourceTemplates, this.prompts,
+			 * this.completions, this.rootsChangeHandlers, this.instructions);
+			 * McpServerFeatures.Async asyncFeatures =
+			 * McpServerFeatures.Async.fromSync(syncFeatures, this.immediateExecution);
+			 * var mapper = this.objectMapper != null ? this.objectMapper : new
+			 * ObjectMapper(); var jsonSchemaValidator = this.jsonSchemaValidator != null
+			 * ? this.jsonSchemaValidator : new DefaultJsonSchemaValidator(mapper);
+			 *
+			 * var asyncServer = new McpAsyncServer(this.transportProvider, mapper,
+			 * asyncFeatures, this.requestTimeout, this.uriTemplateManagerFactory,
+			 * jsonSchemaValidator);
+			 *
+			 * return new McpSyncServer(asyncServer, this.immediateExecution);
+			 */
+			var syncFeatures = new McpStatelessServerFeatures.Sync(this.serverInfo, this.serverCapabilities, this.tools,
+					this.resources, this.resourceTemplates, this.prompts, this.completions, this.instructions);
+			var asyncFeatures = McpStatelessServerFeatures.Async.fromSync(syncFeatures, this.immediateExecution);
+			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
+			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
+					: new DefaultJsonSchemaValidator(mapper);
+			var asyncServer = new McpStatelessAsyncServer(this.transport, mapper, asyncFeatures, this.requestTimeout,
+					this.uriTemplateManagerFactory, jsonSchemaValidator);
+			return new McpStatelessSyncServer(asyncServer, this.immediateExecution);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
new file mode 100644
index 000000000..63fefa31d
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -0,0 +1,671 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.spec.JsonSchemaValidator;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import io.modelcontextprotocol.spec.McpStatelessServerTransport;
+import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.Utils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.function.BiFunction;
+
+/**
+ * A stateless MCP server implementation for use with Streamable HTTP transport types. It
+ * allows simple horizontal scalability since it does not maintain a session and does not
+ * require initialization. Each instance of the server can be reached with no prior
+ * knowledge and can serve the clients with the capabilities it supports.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class McpStatelessAsyncServer {
+
+	private static final Logger logger = LoggerFactory.getLogger(McpStatelessAsyncServer.class);
+
+	private final McpStatelessServerTransport mcpTransportProvider;
+
+	private final ObjectMapper objectMapper;
+
+	private final McpSchema.ServerCapabilities serverCapabilities;
+
+	private final McpSchema.Implementation serverInfo;
+
+	private final String instructions;
+
+	private final CopyOnWriteArrayList tools = new CopyOnWriteArrayList<>();
+
+	private final CopyOnWriteArrayList resourceTemplates = new CopyOnWriteArrayList<>();
+
+	private final ConcurrentHashMap resources = new ConcurrentHashMap<>();
+
+	private final ConcurrentHashMap prompts = new ConcurrentHashMap<>();
+
+	private final ConcurrentHashMap completions = new ConcurrentHashMap<>();
+
+	private List protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
+
+	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+
+	private final JsonSchemaValidator jsonSchemaValidator;
+
+	McpStatelessAsyncServer(McpStatelessServerTransport mcpTransport, ObjectMapper objectMapper,
+			McpStatelessServerFeatures.Async features, Duration requestTimeout,
+			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator) {
+		this.mcpTransportProvider = mcpTransport;
+		this.objectMapper = objectMapper;
+		this.serverInfo = features.serverInfo();
+		this.serverCapabilities = features.serverCapabilities();
+		this.instructions = features.instructions();
+		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
+		this.resources.putAll(features.resources());
+		this.resourceTemplates.addAll(features.resourceTemplates());
+		this.prompts.putAll(features.prompts());
+		this.completions.putAll(features.completions());
+		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+		this.jsonSchemaValidator = jsonSchemaValidator;
+
+		Map> requestHandlers = new HashMap<>();
+
+		// Initialize request handlers for standard MCP methods
+
+		// Ping MUST respond with an empty data, but not NULL response.
+		requestHandlers.put(McpSchema.METHOD_PING, (ctx, params) -> Mono.just(Map.of()));
+
+		requestHandlers.put(McpSchema.METHOD_INITIALIZE, asyncInitializeRequestHandler());
+
+		// Add tools API handlers if the tool capability is enabled
+		if (this.serverCapabilities.tools() != null) {
+			requestHandlers.put(McpSchema.METHOD_TOOLS_LIST, toolsListRequestHandler());
+			requestHandlers.put(McpSchema.METHOD_TOOLS_CALL, toolsCallRequestHandler());
+		}
+
+		// Add resources API handlers if provided
+		if (this.serverCapabilities.resources() != null) {
+			requestHandlers.put(McpSchema.METHOD_RESOURCES_LIST, resourcesListRequestHandler());
+			requestHandlers.put(McpSchema.METHOD_RESOURCES_READ, resourcesReadRequestHandler());
+			requestHandlers.put(McpSchema.METHOD_RESOURCES_TEMPLATES_LIST, resourceTemplateListRequestHandler());
+		}
+
+		// Add prompts API handlers if provider exists
+		if (this.serverCapabilities.prompts() != null) {
+			requestHandlers.put(McpSchema.METHOD_PROMPT_LIST, promptsListRequestHandler());
+			requestHandlers.put(McpSchema.METHOD_PROMPT_GET, promptsGetRequestHandler());
+		}
+
+		// Add completion API handlers if the completion capability is enabled
+		if (this.serverCapabilities.completions() != null) {
+			requestHandlers.put(McpSchema.METHOD_COMPLETION_COMPLETE, completionCompleteRequestHandler());
+		}
+
+		McpStatelessServerHandler handler = new DefaultMcpStatelessServerHandler(requestHandlers, Map.of());
+		mcpTransport.setMcpHandler(handler);
+	}
+
+	// ---------------------------------------
+	// Lifecycle Management
+	// ---------------------------------------
+	private McpStatelessRequestHandler asyncInitializeRequestHandler() {
+		return (ctx, req) -> Mono.defer(() -> {
+			McpSchema.InitializeRequest initializeRequest = this.objectMapper.convertValue(req,
+					McpSchema.InitializeRequest.class);
+
+			logger.info("Client initialize request - Protocol: {}, Capabilities: {}, Info: {}",
+					initializeRequest.protocolVersion(), initializeRequest.capabilities(),
+					initializeRequest.clientInfo());
+
+			// The server MUST respond with the highest protocol version it supports
+			// if
+			// it does not support the requested (e.g. Client) version.
+			String serverProtocolVersion = this.protocolVersions.get(this.protocolVersions.size() - 1);
+
+			if (this.protocolVersions.contains(initializeRequest.protocolVersion())) {
+				// If the server supports the requested protocol version, it MUST
+				// respond
+				// with the same version.
+				serverProtocolVersion = initializeRequest.protocolVersion();
+			}
+			else {
+				logger.warn(
+						"Client requested unsupported protocol version: {}, so the server will suggest the {} version instead",
+						initializeRequest.protocolVersion(), serverProtocolVersion);
+			}
+
+			return Mono.just(new McpSchema.InitializeResult(serverProtocolVersion, this.serverCapabilities,
+					this.serverInfo, this.instructions));
+		});
+	}
+
+	/**
+	 * Get the server capabilities that define the supported features and functionality.
+	 * @return The server capabilities
+	 */
+	public McpSchema.ServerCapabilities getServerCapabilities() {
+		return this.serverCapabilities;
+	}
+
+	/**
+	 * Get the server implementation information.
+	 * @return The server implementation details
+	 */
+	public McpSchema.Implementation getServerInfo() {
+		return this.serverInfo;
+	}
+
+	/**
+	 * Gracefully closes the server, allowing any in-progress operations to complete.
+	 * @return A Mono that completes when the server has been closed
+	 */
+	public Mono closeGracefully() {
+		return this.mcpTransportProvider.closeGracefully();
+	}
+
+	/**
+	 * Close the server immediately.
+	 */
+	public void close() {
+		this.mcpTransportProvider.close();
+	}
+
+	// ---------------------------------------
+	// Tool Management
+	// ---------------------------------------
+
+	private static List withStructuredOutputHandling(
+			JsonSchemaValidator jsonSchemaValidator, List tools) {
+
+		if (Utils.isEmpty(tools)) {
+			return tools;
+		}
+
+		return tools.stream().map(tool -> withStructuredOutputHandling(jsonSchemaValidator, tool)).toList();
+	}
+
+	private static McpStatelessServerFeatures.AsyncToolSpecification withStructuredOutputHandling(
+			JsonSchemaValidator jsonSchemaValidator,
+			McpStatelessServerFeatures.AsyncToolSpecification toolSpecification) {
+
+		if (toolSpecification.callHandler() instanceof StructuredOutputCallToolHandler) {
+			// If the tool is already wrapped, return it as is
+			return toolSpecification;
+		}
+
+		if (toolSpecification.tool().outputSchema() == null) {
+			// If the tool does not have an output schema, return it as is
+			return toolSpecification;
+		}
+
+		return new McpStatelessServerFeatures.AsyncToolSpecification(toolSpecification.tool(),
+				new StructuredOutputCallToolHandler(jsonSchemaValidator, toolSpecification.tool().outputSchema(),
+						toolSpecification.callHandler()));
+	}
+
+	private static class StructuredOutputCallToolHandler
+			implements BiFunction> {
+
+		private final BiFunction> delegateHandler;
+
+		private final JsonSchemaValidator jsonSchemaValidator;
+
+		private final Map outputSchema;
+
+		public StructuredOutputCallToolHandler(JsonSchemaValidator jsonSchemaValidator,
+				Map outputSchema,
+				BiFunction> delegateHandler) {
+
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			Assert.notNull(delegateHandler, "Delegate call tool result handler must not be null");
+
+			this.delegateHandler = delegateHandler;
+			this.outputSchema = outputSchema;
+			this.jsonSchemaValidator = jsonSchemaValidator;
+		}
+
+		@Override
+		public Mono apply(McpTransportContext transportContext, McpSchema.CallToolRequest request) {
+
+			return this.delegateHandler.apply(transportContext, request).map(result -> {
+
+				if (outputSchema == null) {
+					if (result.structuredContent() != null) {
+						logger.warn(
+								"Tool call with no outputSchema is not expected to have a result with structured content, but got: {}",
+								result.structuredContent());
+					}
+					// Pass through. No validation is required if no output schema is
+					// provided.
+					return result;
+				}
+
+				// If an output schema is provided, servers MUST provide structured
+				// results that conform to this schema.
+				// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema
+				if (result.structuredContent() == null) {
+					logger.warn(
+							"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+					return new CallToolResult(
+							"Response missing structured content which is expected when calling tool with non-empty outputSchema",
+							true);
+				}
+
+				// Validate the result against the output schema
+				var validation = this.jsonSchemaValidator.validate(outputSchema, result.structuredContent());
+
+				if (!validation.valid()) {
+					logger.warn("Tool call result validation failed: {}", validation.errorMessage());
+					return new CallToolResult(validation.errorMessage(), true);
+				}
+
+				if (Utils.isEmpty(result.content())) {
+					// For backwards compatibility, a tool that returns structured
+					// content SHOULD also return functionally equivalent unstructured
+					// content. (For example, serialized JSON can be returned in a
+					// TextContent block.)
+					// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
+
+					return new CallToolResult(List.of(new McpSchema.TextContent(validation.jsonStructuredOutput())),
+							result.isError(), result.structuredContent());
+				}
+
+				return result;
+			});
+		}
+
+	}
+
+	/**
+	 * Add a new tool specification at runtime.
+	 * @param toolSpecification The tool specification to add
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono addTool(McpStatelessServerFeatures.AsyncToolSpecification toolSpecification) {
+		if (toolSpecification == null) {
+			return Mono.error(new McpError("Tool specification must not be null"));
+		}
+		if (toolSpecification.tool() == null) {
+			return Mono.error(new McpError("Tool must not be null"));
+		}
+		if (toolSpecification.callHandler() == null) {
+			return Mono.error(new McpError("Tool call handler must not be null"));
+		}
+		if (this.serverCapabilities.tools() == null) {
+			return Mono.error(new McpError("Server must be configured with tool capabilities"));
+		}
+
+		var wrappedToolSpecification = withStructuredOutputHandling(this.jsonSchemaValidator, toolSpecification);
+
+		return Mono.defer(() -> {
+			// Check for duplicate tool names
+			if (this.tools.stream().anyMatch(th -> th.tool().name().equals(wrappedToolSpecification.tool().name()))) {
+				return Mono.error(
+						new McpError("Tool with name '" + wrappedToolSpecification.tool().name() + "' already exists"));
+			}
+
+			this.tools.add(wrappedToolSpecification);
+			logger.debug("Added tool handler: {}", wrappedToolSpecification.tool().name());
+
+			return Mono.empty();
+		});
+	}
+
+	/**
+	 * Remove a tool handler at runtime.
+	 * @param toolName The name of the tool handler to remove
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono removeTool(String toolName) {
+		if (toolName == null) {
+			return Mono.error(new McpError("Tool name must not be null"));
+		}
+		if (this.serverCapabilities.tools() == null) {
+			return Mono.error(new McpError("Server must be configured with tool capabilities"));
+		}
+
+		return Mono.defer(() -> {
+			boolean removed = this.tools
+				.removeIf(toolSpecification -> toolSpecification.tool().name().equals(toolName));
+			if (removed) {
+				logger.debug("Removed tool handler: {}", toolName);
+				return Mono.empty();
+			}
+			return Mono.error(new McpError("Tool with name '" + toolName + "' not found"));
+		});
+	}
+
+	private McpStatelessRequestHandler toolsListRequestHandler() {
+		return (ctx, params) -> {
+			List tools = this.tools.stream()
+				.map(McpStatelessServerFeatures.AsyncToolSpecification::tool)
+				.toList();
+			return Mono.just(new McpSchema.ListToolsResult(tools, null));
+		};
+	}
+
+	private McpStatelessRequestHandler toolsCallRequestHandler() {
+		return (ctx, params) -> {
+			McpSchema.CallToolRequest callToolRequest = objectMapper.convertValue(params,
+					new TypeReference() {
+					});
+
+			Optional toolSpecification = this.tools.stream()
+				.filter(tr -> callToolRequest.name().equals(tr.tool().name()))
+				.findAny();
+
+			if (toolSpecification.isEmpty()) {
+				return Mono.error(new McpError("Tool not found: " + callToolRequest.name()));
+			}
+
+			return toolSpecification.map(tool -> tool.callHandler().apply(ctx, callToolRequest))
+				.orElse(Mono.error(new McpError("Tool not found: " + callToolRequest.name())));
+		};
+	}
+
+	// ---------------------------------------
+	// Resource Management
+	// ---------------------------------------
+
+	/**
+	 * Add a new resource handler at runtime.
+	 * @param resourceSpecification The resource handler to add
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono addResource(McpStatelessServerFeatures.AsyncResourceSpecification resourceSpecification) {
+		if (resourceSpecification == null || resourceSpecification.resource() == null) {
+			return Mono.error(new McpError("Resource must not be null"));
+		}
+
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new McpError("Server must be configured with resource capabilities"));
+		}
+
+		return Mono.defer(() -> {
+			if (this.resources.putIfAbsent(resourceSpecification.resource().uri(), resourceSpecification) != null) {
+				return Mono.error(new McpError(
+						"Resource with URI '" + resourceSpecification.resource().uri() + "' already exists"));
+			}
+			logger.debug("Added resource handler: {}", resourceSpecification.resource().uri());
+			return Mono.empty();
+		});
+	}
+
+	/**
+	 * Remove a resource handler at runtime.
+	 * @param resourceUri The URI of the resource handler to remove
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono removeResource(String resourceUri) {
+		if (resourceUri == null) {
+			return Mono.error(new McpError("Resource URI must not be null"));
+		}
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new McpError("Server must be configured with resource capabilities"));
+		}
+
+		return Mono.defer(() -> {
+			McpStatelessServerFeatures.AsyncResourceSpecification removed = this.resources.remove(resourceUri);
+			if (removed != null) {
+				logger.debug("Removed resource handler: {}", resourceUri);
+				return Mono.empty();
+			}
+			return Mono.error(new McpError("Resource with URI '" + resourceUri + "' not found"));
+		});
+	}
+
+	private McpStatelessRequestHandler resourcesListRequestHandler() {
+		return (ctx, params) -> {
+			var resourceList = this.resources.values()
+				.stream()
+				.map(McpStatelessServerFeatures.AsyncResourceSpecification::resource)
+				.toList();
+			return Mono.just(new McpSchema.ListResourcesResult(resourceList, null));
+		};
+	}
+
+	private McpStatelessRequestHandler resourceTemplateListRequestHandler() {
+		return (ctx, params) -> Mono.just(new McpSchema.ListResourceTemplatesResult(this.getResourceTemplates(), null));
+
+	}
+
+	private List getResourceTemplates() {
+		var list = new ArrayList<>(this.resourceTemplates);
+		List resourceTemplates = this.resources.keySet()
+			.stream()
+			.filter(uri -> uri.contains("{"))
+			.map(uri -> {
+				var resource = this.resources.get(uri).resource();
+				var template = new ResourceTemplate(resource.uri(), resource.name(), resource.title(),
+						resource.description(), resource.mimeType(), resource.annotations());
+				return template;
+			})
+			.toList();
+
+		list.addAll(resourceTemplates);
+
+		return list;
+	}
+
+	private McpStatelessRequestHandler resourcesReadRequestHandler() {
+		return (ctx, params) -> {
+			McpSchema.ReadResourceRequest resourceRequest = objectMapper.convertValue(params,
+					new TypeReference() {
+					});
+			var resourceUri = resourceRequest.uri();
+
+			McpStatelessServerFeatures.AsyncResourceSpecification specification = this.resources.values()
+				.stream()
+				.filter(resourceSpecification -> this.uriTemplateManagerFactory
+					.create(resourceSpecification.resource().uri())
+					.matches(resourceUri))
+				.findFirst()
+				.orElseThrow(() -> new McpError("Resource not found: " + resourceUri));
+
+			return specification.readHandler().apply(ctx, resourceRequest);
+		};
+	}
+
+	// ---------------------------------------
+	// Prompt Management
+	// ---------------------------------------
+
+	/**
+	 * Add a new prompt handler at runtime.
+	 * @param promptSpecification The prompt handler to add
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono addPrompt(McpStatelessServerFeatures.AsyncPromptSpecification promptSpecification) {
+		if (promptSpecification == null) {
+			return Mono.error(new McpError("Prompt specification must not be null"));
+		}
+		if (this.serverCapabilities.prompts() == null) {
+			return Mono.error(new McpError("Server must be configured with prompt capabilities"));
+		}
+
+		return Mono.defer(() -> {
+			McpStatelessServerFeatures.AsyncPromptSpecification specification = this.prompts
+				.putIfAbsent(promptSpecification.prompt().name(), promptSpecification);
+			if (specification != null) {
+				return Mono.error(
+						new McpError("Prompt with name '" + promptSpecification.prompt().name() + "' already exists"));
+			}
+
+			logger.debug("Added prompt handler: {}", promptSpecification.prompt().name());
+
+			return Mono.empty();
+		});
+	}
+
+	/**
+	 * Remove a prompt handler at runtime.
+	 * @param promptName The name of the prompt handler to remove
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono removePrompt(String promptName) {
+		if (promptName == null) {
+			return Mono.error(new McpError("Prompt name must not be null"));
+		}
+		if (this.serverCapabilities.prompts() == null) {
+			return Mono.error(new McpError("Server must be configured with prompt capabilities"));
+		}
+
+		return Mono.defer(() -> {
+			McpStatelessServerFeatures.AsyncPromptSpecification removed = this.prompts.remove(promptName);
+
+			if (removed != null) {
+				logger.debug("Removed prompt handler: {}", promptName);
+				return Mono.empty();
+			}
+			return Mono.error(new McpError("Prompt with name '" + promptName + "' not found"));
+		});
+	}
+
+	private McpStatelessRequestHandler promptsListRequestHandler() {
+		return (ctx, params) -> {
+			// TODO: Implement pagination
+			// McpSchema.PaginatedRequest request = objectMapper.convertValue(params,
+			// new TypeReference() {
+			// });
+
+			var promptList = this.prompts.values()
+				.stream()
+				.map(McpStatelessServerFeatures.AsyncPromptSpecification::prompt)
+				.toList();
+
+			return Mono.just(new McpSchema.ListPromptsResult(promptList, null));
+		};
+	}
+
+	private McpStatelessRequestHandler promptsGetRequestHandler() {
+		return (ctx, params) -> {
+			McpSchema.GetPromptRequest promptRequest = objectMapper.convertValue(params,
+					new TypeReference() {
+					});
+
+			// Implement prompt retrieval logic here
+			McpStatelessServerFeatures.AsyncPromptSpecification specification = this.prompts.get(promptRequest.name());
+			if (specification == null) {
+				return Mono.error(new McpError("Prompt not found: " + promptRequest.name()));
+			}
+
+			return specification.promptHandler().apply(ctx, promptRequest);
+		};
+	}
+
+	private McpStatelessRequestHandler completionCompleteRequestHandler() {
+		return (ctx, params) -> {
+			McpSchema.CompleteRequest request = parseCompletionParams(params);
+
+			if (request.ref() == null) {
+				return Mono.error(new McpError("ref must not be null"));
+			}
+
+			if (request.ref().type() == null) {
+				return Mono.error(new McpError("type must not be null"));
+			}
+
+			String type = request.ref().type();
+
+			String argumentName = request.argument().name();
+
+			// check if the referenced resource exists
+			if (type.equals("ref/prompt") && request.ref() instanceof McpSchema.PromptReference promptReference) {
+				McpStatelessServerFeatures.AsyncPromptSpecification promptSpec = this.prompts
+					.get(promptReference.name());
+				if (promptSpec == null) {
+					return Mono.error(new McpError("Prompt not found: " + promptReference.name()));
+				}
+				if (promptSpec.prompt().arguments().stream().noneMatch(arg -> arg.name().equals(argumentName))) {
+
+					return Mono.error(new McpError("Argument not found: " + argumentName));
+				}
+			}
+
+			if (type.equals("ref/resource") && request.ref() instanceof McpSchema.ResourceReference resourceReference) {
+				McpStatelessServerFeatures.AsyncResourceSpecification resourceSpec = this.resources
+					.get(resourceReference.uri());
+				if (resourceSpec == null) {
+					return Mono.error(new McpError("Resource not found: " + resourceReference.uri()));
+				}
+				if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
+					.getVariableNames()
+					.contains(argumentName)) {
+					return Mono.error(new McpError("Argument not found: " + argumentName));
+				}
+
+			}
+
+			McpStatelessServerFeatures.AsyncCompletionSpecification specification = this.completions.get(request.ref());
+
+			if (specification == null) {
+				return Mono.error(new McpError("AsyncCompletionSpecification not found: " + request.ref()));
+			}
+
+			return specification.completionHandler().apply(ctx, request);
+		};
+	}
+
+	/**
+	 * Parses the raw JSON-RPC request parameters into a {@link McpSchema.CompleteRequest}
+	 * object.
+	 * 

+	 * This method manually extracts the `ref` and `argument` fields from the input map,
+	 * determines the correct reference type (either prompt or resource), and constructs a
+	 * fully-typed {@code CompleteRequest} instance.
+	 * @param object the raw request parameters, expected to be a Map containing "ref" and
+	 * "argument" entries.
+	 * @return a {@link McpSchema.CompleteRequest} representing the structured completion
+	 * request.
+	 * @throws IllegalArgumentException if the "ref" type is not recognized.
+	 */
+	@SuppressWarnings("unchecked")
+	private McpSchema.CompleteRequest parseCompletionParams(Object object) {
+		Map params = (Map) object;
+		Map refMap = (Map) params.get("ref");
+		Map argMap = (Map) params.get("argument");
+
+		String refType = (String) refMap.get("type");
+
+		McpSchema.CompleteReference ref = switch (refType) {
+			case "ref/prompt" -> new McpSchema.PromptReference(refType, (String) refMap.get("name"),
+					refMap.get("title") != null ? (String) refMap.get("title") : null);
+			case "ref/resource" -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
+			default -> throw new IllegalArgumentException("Invalid ref type: " + refType);
+		};
+
+		String argName = (String) argMap.get("name");
+		String argValue = (String) argMap.get("value");
+		McpSchema.CompleteRequest.CompleteArgument argument = new McpSchema.CompleteRequest.CompleteArgument(argName,
+				argValue);
+
+		return new McpSchema.CompleteRequest(ref, argument);
+	}
+
+	/**
+	 * This method is package-private and used for test only. Should not be called by user
+	 * code.
+	 * @param protocolVersions the Client supported protocol versions.
+	 */
+	void setProtocolVersions(List protocolVersions) {
+		this.protocolVersions = protocolVersions;
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
new file mode 100644
index 000000000..d9269a59b
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
@@ -0,0 +1,20 @@
+package io.modelcontextprotocol.server;
+
+import reactor.core.publisher.Mono;
+
+/**
+ * Handler for MCP notifications in a stateless server.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpStatelessNotificationHandler {
+
+	/**
+	 * Handle to notification and complete once done.
+	 * @param transportContext {@link McpTransportContext} associated with the transport
+	 * @param params the payload of the MCP notification
+	 * @return Mono which completes once the processing is done
+	 */
+	Mono handle(McpTransportContext transportContext, Object params);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
new file mode 100644
index 000000000..a6bf0d073
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
@@ -0,0 +1,21 @@
+package io.modelcontextprotocol.server;
+
+import reactor.core.publisher.Mono;
+
+/**
+ * Handler for MCP requests in a stateless server.
+ *
+ * @param  type of the MCP response
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpStatelessRequestHandler {
+
+	/**
+	 * Handle the request and complete with a result.
+	 * @param transportContext {@link McpTransportContext} associated with the transport
+	 * @param params the payload of the MCP request
+	 * @return Mono which completes with the response object
+	 */
+	Mono handle(McpTransportContext transportContext, Object params);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
new file mode 100644
index 000000000..f154272ef
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
@@ -0,0 +1,379 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
+import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.Utils;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.BiFunction;
+
+/**
+ * MCP stateless server features specification that a particular server can choose to
+ * support.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class McpStatelessServerFeatures {
+
+	/**
+	 * Asynchronous server features specification.
+	 *
+	 * @param serverInfo The server implementation details
+	 * @param serverCapabilities The server capabilities
+	 * @param tools The list of tool specifications
+	 * @param resources The map of resource specifications
+	 * @param resourceTemplates The list of resource templates
+	 * @param prompts The map of prompt specifications
+	 * @param instructions The server instructions text
+	 */
+	record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
+			List tools,
+			Map resources, List resourceTemplates,
+			Map prompts,
+			Map completions,
+			String instructions) {
+
+		/**
+		 * Create an instance and validate the arguments.
+		 * @param serverInfo The server implementation details
+		 * @param serverCapabilities The server capabilities
+		 * @param tools The list of tool specifications
+		 * @param resources The map of resource specifications
+		 * @param resourceTemplates The list of resource templates
+		 * @param prompts The map of prompt specifications
+		 * @param instructions The server instructions text
+		 */
+		Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
+				List tools,
+				Map resources, List resourceTemplates,
+				Map prompts,
+				Map completions,
+				String instructions) {
+
+			Assert.notNull(serverInfo, "Server info must not be null");
+
+			this.serverInfo = serverInfo;
+			this.serverCapabilities = (serverCapabilities != null) ? serverCapabilities
+					: new McpSchema.ServerCapabilities(null, // completions
+							null, // experimental
+							new McpSchema.ServerCapabilities.LoggingCapabilities(), // Enable
+																					// logging
+																					// by
+																					// default
+							!Utils.isEmpty(prompts) ? new McpSchema.ServerCapabilities.PromptCapabilities(false) : null,
+							!Utils.isEmpty(resources)
+									? new McpSchema.ServerCapabilities.ResourceCapabilities(false, false) : null,
+							!Utils.isEmpty(tools) ? new McpSchema.ServerCapabilities.ToolCapabilities(false) : null);
+
+			this.tools = (tools != null) ? tools : List.of();
+			this.resources = (resources != null) ? resources : Map.of();
+			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : List.of();
+			this.prompts = (prompts != null) ? prompts : Map.of();
+			this.completions = (completions != null) ? completions : Map.of();
+			this.instructions = instructions;
+		}
+
+		/**
+		 * Convert a synchronous specification into an asynchronous one and provide
+		 * blocking code offloading to prevent accidental blocking of the non-blocking
+		 * transport.
+		 * @param syncSpec a potentially blocking, synchronous specification.
+		 * @param immediateExecution when true, do not offload. Do NOT set to true when
+		 * using a non-blocking transport.
+		 * @return a specification which is protected from blocking calls specified by the
+		 * user.
+		 */
+		static Async fromSync(Sync syncSpec, boolean immediateExecution) {
+			List tools = new ArrayList<>();
+			for (var tool : syncSpec.tools()) {
+				tools.add(AsyncToolSpecification.fromSync(tool, immediateExecution));
+			}
+
+			Map resources = new HashMap<>();
+			syncSpec.resources().forEach((key, resource) -> {
+				resources.put(key, AsyncResourceSpecification.fromSync(resource, immediateExecution));
+			});
+
+			Map prompts = new HashMap<>();
+			syncSpec.prompts().forEach((key, prompt) -> {
+				prompts.put(key, AsyncPromptSpecification.fromSync(prompt, immediateExecution));
+			});
+
+			Map completions = new HashMap<>();
+			syncSpec.completions().forEach((key, completion) -> {
+				completions.put(key, AsyncCompletionSpecification.fromSync(completion, immediateExecution));
+			});
+
+			return new Async(syncSpec.serverInfo(), syncSpec.serverCapabilities(), tools, resources,
+					syncSpec.resourceTemplates(), prompts, completions, syncSpec.instructions());
+		}
+	}
+
+	/**
+	 * Synchronous server features specification.
+	 *
+	 * @param serverInfo The server implementation details
+	 * @param serverCapabilities The server capabilities
+	 * @param tools The list of tool specifications
+	 * @param resources The map of resource specifications
+	 * @param resourceTemplates The list of resource templates
+	 * @param prompts The map of prompt specifications
+	 * @param instructions The server instructions text
+	 */
+	record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
+			List tools,
+			Map resources,
+			List resourceTemplates,
+			Map prompts,
+			Map completions,
+			String instructions) {
+
+		/**
+		 * Create an instance and validate the arguments.
+		 * @param serverInfo The server implementation details
+		 * @param serverCapabilities The server capabilities
+		 * @param tools The list of tool specifications
+		 * @param resources The map of resource specifications
+		 * @param resourceTemplates The list of resource templates
+		 * @param prompts The map of prompt specifications
+		 * @param instructions The server instructions text
+		 */
+		Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
+				List tools,
+				Map resources,
+				List resourceTemplates,
+				Map prompts,
+				Map completions,
+				String instructions) {
+
+			Assert.notNull(serverInfo, "Server info must not be null");
+
+			this.serverInfo = serverInfo;
+			this.serverCapabilities = (serverCapabilities != null) ? serverCapabilities
+					: new McpSchema.ServerCapabilities(null, // completions
+							null, // experimental
+							new McpSchema.ServerCapabilities.LoggingCapabilities(), // Enable
+																					// logging
+																					// by
+																					// default
+							!Utils.isEmpty(prompts) ? new McpSchema.ServerCapabilities.PromptCapabilities(false) : null,
+							!Utils.isEmpty(resources)
+									? new McpSchema.ServerCapabilities.ResourceCapabilities(false, false) : null,
+							!Utils.isEmpty(tools) ? new McpSchema.ServerCapabilities.ToolCapabilities(false) : null);
+
+			this.tools = (tools != null) ? tools : new ArrayList<>();
+			this.resources = (resources != null) ? resources : new HashMap<>();
+			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : new ArrayList<>();
+			this.prompts = (prompts != null) ? prompts : new HashMap<>();
+			this.completions = (completions != null) ? completions : new HashMap<>();
+			this.instructions = instructions;
+		}
+
+	}
+
+	/**
+	 * Specification of a tool with its asynchronous handler function. Tools are the
+	 * primary way for MCP servers to expose functionality to AI models. Each tool
+	 * represents a specific capability.
+	 *
+	 * @param tool The tool definition including name, description, and parameter schema
+	 * @param callHandler The function that implements the tool's logic, receiving a
+	 * {@link CallToolRequest} and returning the result.
+	 */
+	public record AsyncToolSpecification(McpSchema.Tool tool,
+			BiFunction> callHandler) {
+
+		static AsyncToolSpecification fromSync(SyncToolSpecification syncToolSpec) {
+			return fromSync(syncToolSpec, false);
+		}
+
+		static AsyncToolSpecification fromSync(SyncToolSpecification syncToolSpec, boolean immediate) {
+
+			// FIXME: This is temporary, proper validation should be implemented
+			if (syncToolSpec == null) {
+				return null;
+			}
+
+			BiFunction> callHandler = (ctx,
+					req) -> {
+				var toolResult = Mono.fromCallable(() -> syncToolSpec.callHandler().apply(ctx, req));
+				return immediate ? toolResult : toolResult.subscribeOn(Schedulers.boundedElastic());
+			};
+
+			return new AsyncToolSpecification(syncToolSpec.tool(), callHandler);
+		}
+	}
+
+	/**
+	 * Specification of a resource with its asynchronous handler function. Resources
+	 * provide context to AI models by exposing data such as:
+	 * 
    
+	 * 
  • File contents
+	 * 
  • Database records
+	 * 
  • API responses
+	 * 
  • System information
+	 * 
  • Application state
+	 * 

+	 *
+	 * @param resource The resource definition including name, description, and MIME type
+	 * @param readHandler The function that handles resource read requests. The function's
+	 * argument is a {@link McpSchema.ReadResourceRequest}.
+	 */
+	public record AsyncResourceSpecification(McpSchema.Resource resource,
+			BiFunction> readHandler) {
+
+		static AsyncResourceSpecification fromSync(SyncResourceSpecification resource, boolean immediateExecution) {
+			// FIXME: This is temporary, proper validation should be implemented
+			if (resource == null) {
+				return null;
+			}
+			return new AsyncResourceSpecification(resource.resource(), (ctx, req) -> {
+				var resourceResult = Mono.fromCallable(() -> resource.readHandler().apply(ctx, req));
+				return immediateExecution ? resourceResult : resourceResult.subscribeOn(Schedulers.boundedElastic());
+			});
+		}
+	}
+
+	/**
+	 * Specification of a prompt template with its asynchronous handler function. Prompts
+	 * provide structured templates for AI model interactions, supporting:
+	 * 
    
+	 * 
  • Consistent message formatting
+	 * 
  • Parameter substitution
+	 * 
  • Context injection
+	 * 
  • Response formatting
+	 * 
  • Instruction templating
+	 * 

+	 *
+	 * @param prompt The prompt definition including name and description
+	 * @param promptHandler The function that processes prompt requests and returns
+	 * formatted templates. The function's argument is a
+	 * {@link McpSchema.GetPromptRequest}.
+	 */
+	public record AsyncPromptSpecification(McpSchema.Prompt prompt,
+			BiFunction> promptHandler) {
+
+		static AsyncPromptSpecification fromSync(SyncPromptSpecification prompt, boolean immediateExecution) {
+			// FIXME: This is temporary, proper validation should be implemented
+			if (prompt == null) {
+				return null;
+			}
+			return new AsyncPromptSpecification(prompt.prompt(), (ctx, req) -> {
+				var promptResult = Mono.fromCallable(() -> prompt.promptHandler().apply(ctx, req));
+				return immediateExecution ? promptResult : promptResult.subscribeOn(Schedulers.boundedElastic());
+			});
+		}
+	}
+
+	/**
+	 * Specification of a completion handler function with asynchronous execution support.
+	 * Completions generate AI model outputs based on prompt or resource references and
+	 * user-provided arguments. This abstraction enables:
+	 * 
    
+	 * 
  • Customizable response generation logic
+	 * 
  • Parameter-driven template expansion
+	 * 
  • Dynamic interaction with connected clients
+	 * 

+	 *
+	 * @param referenceKey The unique key representing the completion reference.
+	 * @param completionHandler The asynchronous function that processes completion
+	 * requests and returns results. The function's argument is a
+	 * {@link McpSchema.CompleteRequest}.
+	 */
+	public record AsyncCompletionSpecification(McpSchema.CompleteReference referenceKey,
+			BiFunction> completionHandler) {
+
+		/**
+		 * Converts a synchronous {@link SyncCompletionSpecification} into an
+		 * {@link AsyncCompletionSpecification} by wrapping the handler in a bounded
+		 * elastic scheduler for safe non-blocking execution.
+		 * @param completion the synchronous completion specification
+		 * @return an asynchronous wrapper of the provided sync specification, or
+		 * {@code null} if input is null
+		 */
+		static AsyncCompletionSpecification fromSync(SyncCompletionSpecification completion,
+				boolean immediateExecution) {
+			if (completion == null) {
+				return null;
+			}
+			return new AsyncCompletionSpecification(completion.referenceKey(), (ctx, req) -> {
+				var completionResult = Mono.fromCallable(() -> completion.completionHandler().apply(ctx, req));
+				return immediateExecution ? completionResult
+						: completionResult.subscribeOn(Schedulers.boundedElastic());
+			});
+		}
+	}
+
+	/**
+	 * Specification of a tool with its synchronous handler function. Tools are the
+	 * primary way for MCP servers to expose functionality to AI models.
+	 *
+	 * @param tool The tool definition including name, description, and parameter schema
+	 * @param callHandler The function that implements the tool's logic, receiving a
+	 * {@link CallToolRequest} and returning results.
+	 */
+	public record SyncToolSpecification(McpSchema.Tool tool,
+			BiFunction callHandler) {
+	}
+
+	/**
+	 * Specification of a resource with its synchronous handler function. Resources
+	 * provide context to AI models by exposing data such as:
+	 * 
    
+	 * 
  • File contents
+	 * 
  • Database records
+	 * 
  • API responses
+	 * 
  • System information
+	 * 
  • Application state
+	 * 

+	 *
+	 * @param resource The resource definition including name, description, and MIME type
+	 * @param readHandler The function that handles resource read requests. The function's
+	 * argument is a {@link McpSchema.ReadResourceRequest}.
+	 */
+	public record SyncResourceSpecification(McpSchema.Resource resource,
+			BiFunction readHandler) {
+	}
+
+	/**
+	 * Specification of a prompt template with its synchronous handler function. Prompts
+	 * provide structured templates for AI model interactions, supporting:
+	 * 
    
+	 * 
  • Consistent message formatting
+	 * 
  • Parameter substitution
+	 * 
  • Context injection
+	 * 
  • Response formatting
+	 * 
  • Instruction templating
+	 * 

+	 *
+	 * @param prompt The prompt definition including name and description
+	 * @param promptHandler The function that processes prompt requests and returns
+	 * formatted templates. The function's argument is a
+	 * {@link McpSchema.GetPromptRequest}.
+	 */
+	public record SyncPromptSpecification(McpSchema.Prompt prompt,
+			BiFunction promptHandler) {
+	}
+
+	/**
+	 * Specification of a completion handler function with synchronous execution support.
+	 *
+	 * @param referenceKey The unique key representing the completion reference.
+	 * @param completionHandler The synchronous function that processes completion
+	 * requests and returns results. The argument is a {@link McpSchema.CompleteRequest}.
+	 */
+	public record SyncCompletionSpecification(McpSchema.CompleteReference referenceKey,
+			BiFunction completionHandler) {
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
new file mode 100644
index 000000000..80884435e
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
@@ -0,0 +1,33 @@
+package io.modelcontextprotocol.server;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import reactor.core.publisher.Mono;
+
+/**
+ * Handler for MCP requests and notifications in a Stateless Streamable HTTP Server
+ * context.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpStatelessServerHandler {
+
+	/**
+	 * Handle the request using user-provided feature implementations.
+	 * @param transportContext {@link McpTransportContext} carrying transport layer
+	 * metadata
+	 * @param request the request JSON object
+	 * @return Mono containing the JSON response
+	 */
+	Mono handleRequest(McpTransportContext transportContext,
+			McpSchema.JSONRPCRequest request);
+
+	/**
+	 * Handle the notification.
+	 * @param transportContext {@link McpTransportContext} carrying transport layer
+	 * metadata
+	 * @param notification the notification JSON object
+	 * @return Mono that completes once handling is finished
+	 */
+	Mono handleNotification(McpTransportContext transportContext, McpSchema.JSONRPCNotification notification);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
new file mode 100644
index 000000000..0151a754b
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
@@ -0,0 +1,132 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+
+/**
+ * A stateless MCP server implementation for use with Streamable HTTP transport types. It
+ * allows simple horizontal scalability since it does not maintain a session and does not
+ * require initialization. Each instance of the server can be reached with no prior
+ * knowledge and can serve the clients with the capabilities it supports.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class McpStatelessSyncServer {
+
+	private static final Logger logger = LoggerFactory.getLogger(McpStatelessSyncServer.class);
+
+	private final McpStatelessAsyncServer asyncServer;
+
+	private final boolean immediateExecution;
+
+	McpStatelessSyncServer(McpStatelessAsyncServer asyncServer, boolean immediateExecution) {
+		this.asyncServer = asyncServer;
+		this.immediateExecution = immediateExecution;
+	}
+
+	/**
+	 * Get the server capabilities that define the supported features and functionality.
+	 * @return The server capabilities
+	 */
+	public McpSchema.ServerCapabilities getServerCapabilities() {
+		return this.asyncServer.getServerCapabilities();
+	}
+
+	/**
+	 * Get the server implementation information.
+	 * @return The server implementation details
+	 */
+	public McpSchema.Implementation getServerInfo() {
+		return this.asyncServer.getServerInfo();
+	}
+
+	/**
+	 * Gracefully closes the server, allowing any in-progress operations to complete.
+	 * @return A Mono that completes when the server has been closed
+	 */
+	public Mono closeGracefully() {
+		return this.asyncServer.closeGracefully();
+	}
+
+	/**
+	 * Close the server immediately.
+	 */
+	public void close() {
+		this.asyncServer.close();
+	}
+
+	/**
+	 * Add a new tool specification at runtime.
+	 * @param toolSpecification The tool specification to add
+	 */
+	public void addTool(McpStatelessServerFeatures.SyncToolSpecification toolSpecification) {
+		this.asyncServer
+			.addTool(McpStatelessServerFeatures.AsyncToolSpecification.fromSync(toolSpecification,
+					this.immediateExecution))
+			.block();
+	}
+
+	/**
+	 * Remove a tool handler at runtime.
+	 * @param toolName The name of the tool handler to remove
+	 */
+	public void removeTool(String toolName) {
+		this.asyncServer.removeTool(toolName).block();
+	}
+
+	/**
+	 * Add a new resource handler at runtime.
+	 * @param resourceSpecification The resource handler to add
+	 */
+	public void addResource(McpStatelessServerFeatures.SyncResourceSpecification resourceSpecification) {
+		this.asyncServer
+			.addResource(McpStatelessServerFeatures.AsyncResourceSpecification.fromSync(resourceSpecification,
+					this.immediateExecution))
+			.block();
+	}
+
+	/**
+	 * Remove a resource handler at runtime.
+	 * @param resourceUri The URI of the resource handler to remove
+	 */
+	public void removeResource(String resourceUri) {
+		this.asyncServer.removeResource(resourceUri).block();
+	}
+
+	/**
+	 * Add a new prompt handler at runtime.
+	 * @param promptSpecification The prompt handler to add
+	 */
+	public void addPrompt(McpStatelessServerFeatures.SyncPromptSpecification promptSpecification) {
+		this.asyncServer
+			.addPrompt(McpStatelessServerFeatures.AsyncPromptSpecification.fromSync(promptSpecification,
+					this.immediateExecution))
+			.block();
+	}
+
+	/**
+	 * Remove a prompt handler at runtime.
+	 * @param promptName The name of the prompt handler to remove
+	 */
+	public void removePrompt(String promptName) {
+		this.asyncServer.removePrompt(promptName).block();
+	}
+
+	/**
+	 * This method is package-private and used for test only. Should not be called by user
+	 * code.
+	 * @param protocolVersions the Client supported protocol versions.
+	 */
+	void setProtocolVersions(List protocolVersions) {
+		this.asyncServer.setProtocolVersions(protocolVersions);
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
index dad1e4c19..5f22df5e9 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
@@ -27,6 +27,14 @@ public McpSyncServerExchange(McpAsyncServerExchange exchange) {
 		this.exchange = exchange;
 	}
 
+	/**
+	 * Provides the Session ID
+	 * @return session ID
+	 */
+	public String sessionId() {
+		return this.exchange.sessionId();
+	}
+
 	/**
 	 * Get the client capabilities that define the supported features and functionality.
 	 * @return The client capabilities
@@ -43,6 +51,16 @@ public McpSchema.Implementation getClientInfo() {
 		return this.exchange.getClientInfo();
 	}
 
+	/**
+	 * Provides the {@link McpTransportContext} associated with the transport layer. For
+	 * HTTP transports it can contain the metadata associated with the HTTP request that
+	 * triggered the processing.
+	 * @return the transport context object
+	 */
+	public McpTransportContext transportContext() {
+		return this.exchange.transportContext();
+	}
+
 	/**
 	 * Create a new message using the sampling capabilities of the client. The Model
 	 * Context Protocol (MCP) provides a standardized way for servers to request LLM
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
new file mode 100644
index 000000000..3d51bb6e2
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
@@ -0,0 +1,46 @@
+package io.modelcontextprotocol.server;
+
+import java.util.Collections;
+
+/**
+ * Context associated with the transport layer. It allows to add transport-level metadata
+ * for use further down the line. Specifically, it can be beneficial to extract HTTP
+ * request metadata for use in MCP feature implementations.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpTransportContext {
+
+	/**
+	 * Key for use in Reactor Context to transport the context to user land.
+	 */
+	String KEY = "MCP_TRANSPORT_CONTEXT";
+
+	/**
+	 * An empty, unmodifiable context.
+	 */
+	@SuppressWarnings("unchecked")
+	McpTransportContext EMPTY = new DefaultMcpTransportContext(Collections.EMPTY_MAP);
+
+	/**
+	 * Extract a value from the context.
+	 * @param key the key under the data is expected
+	 * @return the associated value or {@code null} if missing.
+	 */
+	Object get(String key);
+
+	/**
+	 * Inserts a value for a given key.
+	 * @param key a String representing the key
+	 * @param value the value to store
+	 */
+	void put(String key, Object value);
+
+	/**
+	 * Copies the contents of the context to allow further modifications without affecting
+	 * the initial object.
+	 * @return a new instance with the underlying storage copied.
+	 */
+	McpTransportContext copy();
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
new file mode 100644
index 000000000..472de8195
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
@@ -0,0 +1,24 @@
+package io.modelcontextprotocol.server;
+
+/**
+ * The contract for extracting metadata from a generic transport request of type
+ * {@link T}.
+ *
+ * @param  transport-specific representation of the request which allows extracting
+ * metadata for use in the MCP features implementations.
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpTransportContextExtractor {
+
+	/**
+	 * Given an empty context, provides the means to fill it with transport-specific
+	 * metadata extracted from the request.
+	 * @param request the generic representation for the request in the context of a
+	 * specific transport implementation
+	 * @param transportContext the mutable context which can be filled in with metadata
+	 * @return the context filled in with metadata. It can be the same instance as
+	 * provided or a new one.
+	 */
+	McpTransportContext extract(T request, McpTransportContext transportContext);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
new file mode 100644
index 000000000..8533e69cf
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
@@ -0,0 +1,52 @@
+package io.modelcontextprotocol.spec;
+
+import io.modelcontextprotocol.server.McpNotificationHandler;
+import io.modelcontextprotocol.server.McpRequestHandler;
+import reactor.core.publisher.Mono;
+
+import java.time.Duration;
+import java.util.Map;
+import java.util.UUID;
+
+/**
+ * A default implementation of {@link McpStreamableServerSession.Factory}.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class DefaultMcpStreamableServerSessionFactory implements McpStreamableServerSession.Factory {
+
+	Duration requestTimeout;
+
+	McpStreamableServerSession.InitRequestHandler initRequestHandler;
+
+	Map> requestHandlers;
+
+	Map notificationHandlers;
+
+	/**
+	 * Constructs an instance
+	 * @param requestTimeout timeout for requests
+	 * @param initRequestHandler initialization request handler
+	 * @param requestHandlers map of MCP request handlers keyed by method name
+	 * @param notificationHandlers map of MCP notification handlers keyed by method name
+	 */
+	public DefaultMcpStreamableServerSessionFactory(Duration requestTimeout,
+			McpStreamableServerSession.InitRequestHandler initRequestHandler,
+			Map> requestHandlers,
+			Map notificationHandlers) {
+		this.requestTimeout = requestTimeout;
+		this.initRequestHandler = initRequestHandler;
+		this.requestHandlers = requestHandlers;
+		this.notificationHandlers = notificationHandlers;
+	}
+
+	@Override
+	public McpStreamableServerSession.McpStreamableServerSessionInit startSession(
+			McpSchema.InitializeRequest initializeRequest) {
+		return new McpStreamableServerSession.McpStreamableServerSessionInit(
+				new McpStreamableServerSession(UUID.randomUUID().toString(), initializeRequest.capabilities(),
+						initializeRequest.clientInfo(), requestTimeout, requestHandlers, notificationHandlers),
+				this.initRequestHandler.handle(initializeRequest));
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
new file mode 100644
index 000000000..2e8084915
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
@@ -0,0 +1,20 @@
+package io.modelcontextprotocol.spec;
+
+/**
+ * Names of HTTP headers in use by MCP HTTP transports.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface HttpHeaders {
+
+	/**
+	 * Identifies individual MCP sessions.
+	 */
+	String MCP_SESSION_ID = "mcp-session-id";
+
+	/**
+	 * Identifies events within an SSE Stream.
+	 */
+	String LAST_EVENT_ID = "last-event-id";
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
new file mode 100644
index 000000000..ebc6e0949
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
@@ -0,0 +1,25 @@
+package io.modelcontextprotocol.spec;
+
+/**
+ * An {@link McpSession} which is capable of processing logging notifications and keeping
+ * track of a min logging level.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpLoggableSession extends McpSession {
+
+	/**
+	 * Set the minimum logging level for the client. Messages below this level will be
+	 * filtered out.
+	 * @param minLoggingLevel The minimum logging level
+	 */
+	void setMinLoggingLevel(McpSchema.LoggingLevel minLoggingLevel);
+
+	/**
+	 * Allows checking whether a particular logging level is allowed.
+	 * @param loggingLevel the level to check
+	 * @return whether the logging at the specified level is permitted.
+	 */
+	boolean isNotificationForLevelAllowed(McpSchema.LoggingLevel loggingLevel);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index e9c23db6a..a3812dbc2 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -44,7 +44,7 @@ public final class McpSchema {
 	private McpSchema() {
 	}
 
-	public static final String LATEST_PROTOCOL_VERSION = "2024-11-05";
+	public static final String LATEST_PROTOCOL_VERSION = "2025-03-26";
 
 	public static final String JSONRPC_VERSION = "2.0";
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index 86906d859..0b0ef01cd 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -9,6 +9,11 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
+import io.modelcontextprotocol.server.McpInitRequestHandler;
+import io.modelcontextprotocol.server.McpNotificationHandler;
+import io.modelcontextprotocol.server.McpRequestHandler;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Mono;
@@ -19,7 +24,7 @@
  * Represents a Model Control Protocol (MCP) session on the server side. It manages
  * bidirectional JSON-RPC communication with the client.
  */
-public class McpServerSession implements McpSession {
+public class McpServerSession implements McpLoggableSession {
 
 	private static final Logger logger = LoggerFactory.getLogger(McpServerSession.class);
 
@@ -32,13 +37,11 @@ public class McpServerSession implements McpSession {
 
 	private final AtomicLong requestCounter = new AtomicLong(0);
 
-	private final InitRequestHandler initRequestHandler;
+	private final McpInitRequestHandler initRequestHandler;
 
-	private final InitNotificationHandler initNotificationHandler;
+	private final Map> requestHandlers;
 
-	private final Map> requestHandlers;
-
-	private final Map notificationHandlers;
+	private final Map notificationHandlers;
 
 	private final McpServerTransport transport;
 
@@ -56,6 +59,29 @@ public class McpServerSession implements McpSession {
 
 	private final AtomicInteger state = new AtomicInteger(STATE_UNINITIALIZED);
 
+	private volatile McpSchema.LoggingLevel minLoggingLevel = McpSchema.LoggingLevel.INFO;
+
+	/**
+	 * Creates a new server session with the given parameters and the transport to use.
+	 * @param id session id
+	 * @param transport the transport to use
+	 * @param initHandler called when a
+	 * {@link io.modelcontextprotocol.spec.McpSchema.InitializeRequest} is received by the
+	 * server
+	 * @param requestHandlers map of request handlers to use
+	 * @param notificationHandlers map of notification handlers to use
+	 */
+	public McpServerSession(String id, Duration requestTimeout, McpServerTransport transport,
+			McpInitRequestHandler initHandler, Map> requestHandlers,
+			Map notificationHandlers) {
+		this.id = id;
+		this.requestTimeout = requestTimeout;
+		this.transport = transport;
+		this.initRequestHandler = initHandler;
+		this.requestHandlers = requestHandlers;
+		this.notificationHandlers = notificationHandlers;
+	}
+
 	/**
 	 * Creates a new server session with the given parameters and the transport to use.
 	 * @param id session id
@@ -68,15 +94,18 @@ public class McpServerSession implements McpSession {
 	 * received.
 	 * @param requestHandlers map of request handlers to use
 	 * @param notificationHandlers map of notification handlers to use
+	 * @deprecated Use
+	 * {@link #McpServerSession(String, Duration, McpServerTransport, McpInitRequestHandler, Map, Map)}
 	 */
+	@Deprecated
 	public McpServerSession(String id, Duration requestTimeout, McpServerTransport transport,
-			InitRequestHandler initHandler, InitNotificationHandler initNotificationHandler,
-			Map> requestHandlers, Map notificationHandlers) {
+			McpInitRequestHandler initHandler, InitNotificationHandler initNotificationHandler,
+			Map> requestHandlers,
+			Map notificationHandlers) {
 		this.id = id;
 		this.requestTimeout = requestTimeout;
 		this.transport = transport;
 		this.initRequestHandler = initHandler;
-		this.initNotificationHandler = initNotificationHandler;
 		this.requestHandlers = requestHandlers;
 		this.notificationHandlers = notificationHandlers;
 	}
@@ -108,6 +137,17 @@ private String generateRequestId() {
 		return this.id + "-" + this.requestCounter.getAndIncrement();
 	}
 
+	@Override
+	public void setMinLoggingLevel(McpSchema.LoggingLevel minLoggingLevel) {
+		Assert.notNull(minLoggingLevel, "minLoggingLevel must not be null");
+		this.minLoggingLevel = minLoggingLevel;
+	}
+
+	@Override
+	public boolean isNotificationForLevelAllowed(McpSchema.LoggingLevel loggingLevel) {
+		return loggingLevel.level() >= this.minLoggingLevel.level();
+	}
+
 	@Override
 	public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
 		String requestId = this.generateRequestId();
@@ -242,8 +282,10 @@ private Mono handleIncomingNotification(McpSchema.JSONRPCNotification noti
 		return Mono.defer(() -> {
 			if (McpSchema.METHOD_NOTIFICATION_INITIALIZED.equals(notification.method())) {
 				this.state.lazySet(STATE_INITIALIZED);
-				exchangeSink.tryEmitValue(new McpAsyncServerExchange(this, clientCapabilities.get(), clientInfo.get()));
-				return this.initNotificationHandler.handle();
+				// FIXME: The session ID passed here is not the same as the one in the
+				// legacy SSE transport.
+				exchangeSink.tryEmitValue(new McpAsyncServerExchange(this.id, this, clientCapabilities.get(),
+						clientInfo.get(), McpTransportContext.EMPTY));
 			}
 
 			var handler = notificationHandlers.get(notification.method());
@@ -264,17 +306,22 @@ private MethodNotFoundError getMethodNotFoundError(String method) {
 
 	@Override
 	public Mono closeGracefully() {
+		// TODO: clear pendingResponses and emit errors?
 		return this.transport.closeGracefully();
 	}
 
 	@Override
 	public void close() {
+		// TODO: clear pendingResponses and emit errors?
 		this.transport.close();
 	}
 
 	/**
 	 * Request handler for the initialization request.
+	 *
+	 * @deprecated Use {@link McpInitRequestHandler}
 	 */
+	@Deprecated
 	public interface InitRequestHandler {
 
 		/**
@@ -301,7 +348,10 @@ public interface InitNotificationHandler {
 
 	/**
 	 * A handler for client-initiated notifications.
+	 *
+	 * @deprecated Use {@link McpNotificationHandler}
 	 */
+	@Deprecated
 	public interface NotificationHandler {
 
 		/**
@@ -320,7 +370,9 @@ public interface NotificationHandler {
 	 *
 	 * @param  the type of the response that is expected as a result of handling the
 	 * request.
+	 * @deprecated Use {@link McpRequestHandler}
 	 */
+	@Deprecated
 	public interface RequestHandler {
 
 		/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
index 5fdbd7ab6..382c0153b 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
@@ -1,35 +1,12 @@
 package io.modelcontextprotocol.spec;
 
-import java.util.Map;
-
-import reactor.core.publisher.Mono;
-
 /**
- * The core building block providing the server-side MCP transport. Implement this
- * interface to bridge between a particular server-side technology and the MCP server
- * transport layer.
- *
- * 

- * The lifecycle of the provider dictates that it be created first, upon application
- * startup, and then passed into either
- * {@link io.modelcontextprotocol.server.McpServer#sync(McpServerTransportProvider)} or
- * {@link io.modelcontextprotocol.server.McpServer#async(McpServerTransportProvider)}. As
- * a result of the MCP server creation, the provider will be notified of a
- * {@link McpServerSession.Factory} which will be used to handle a 1:1 communication
- * between a newly connected client and the server. The provider's responsibility is to
- * create instances of {@link McpServerTransport} that the session will utilise during the
- * session lifetime.
- *
- * 

- * Finally, the {@link McpServerTransport}s can be closed in bulk when {@link #close()} or
- * {@link #closeGracefully()} are called as part of the normal application shutdown event.
- * Individual {@link McpServerTransport}s can also be closed on a per-session basis, where
- * the {@link McpServerSession#close()} or {@link McpServerSession#closeGracefully()}
- * closes the provided transport.
+ * Classic implementation of {@link McpServerTransportProviderBase} for a single outgoing
+ * stream in bidirectional communication (STDIO and the legacy HTTP SSE).
  *
  * @author Dariusz Jędrzejczyk
  */
-public interface McpServerTransportProvider {
+public interface McpServerTransportProvider extends McpServerTransportProviderBase {
 
 	/**
 	 * Sets the session factory that will be used to create sessions for new clients. An
@@ -39,28 +16,4 @@ public interface McpServerTransportProvider {
 	 */
 	void setSessionFactory(McpServerSession.Factory sessionFactory);
 
-	/**
-	 * Sends a notification to all connected clients.
-	 * @param method the name of the notification method to be called on the clients
-	 * @param params parameters to be sent with the notification
-	 * @return a Mono that completes when the notification has been broadcast
-	 * @see McpSession#sendNotification(String, Map)
-	 */
-	Mono notifyClients(String method, Object params);
-
-	/**
-	 * Immediately closes all the transports with connected clients and releases any
-	 * associated resources.
-	 */
-	default void close() {
-		this.closeGracefully().subscribe();
-	}
-
-	/**
-	 * Gracefully closes all the transports with connected clients and releases any
-	 * associated resources asynchronously.
-	 * @return a {@link Mono} that completes when the connections have been closed.
-	 */
-	Mono closeGracefully();
-
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
new file mode 100644
index 000000000..87e7d6441
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
@@ -0,0 +1,58 @@
+package io.modelcontextprotocol.spec;
+
+import java.util.Map;
+
+import reactor.core.publisher.Mono;
+
+/**
+ * The core building block providing the server-side MCP transport. Implement this
+ * interface to bridge between a particular server-side technology and the MCP server
+ * transport layer.
+ *
+ * 

+ * The lifecycle of the provider dictates that it be created first, upon application
+ * startup, and then passed into either
+ * {@link io.modelcontextprotocol.server.McpServer#sync(McpServerTransportProvider)} or
+ * {@link io.modelcontextprotocol.server.McpServer#async(McpServerTransportProvider)}. As
+ * a result of the MCP server creation, the provider will be notified of a
+ * {@link McpServerSession.Factory} which will be used to handle a 1:1 communication
+ * between a newly connected client and the server. The provider's responsibility is to
+ * create instances of {@link McpServerTransport} that the session will utilise during the
+ * session lifetime.
+ *
+ * 

+ * Finally, the {@link McpServerTransport}s can be closed in bulk when {@link #close()} or
+ * {@link #closeGracefully()} are called as part of the normal application shutdown event.
+ * Individual {@link McpServerTransport}s can also be closed on a per-session basis, where
+ * the {@link McpServerSession#close()} or {@link McpServerSession#closeGracefully()}
+ * closes the provided transport.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpServerTransportProviderBase {
+
+	/**
+	 * Sends a notification to all connected clients.
+	 * @param method the name of the notification method to be called on the clients
+	 * @param params parameters to be sent with the notification
+	 * @return a Mono that completes when the notification has been broadcast
+	 * @see McpSession#sendNotification(String, Map)
+	 */
+	Mono notifyClients(String method, Object params);
+
+	/**
+	 * Immediately closes all the transports with connected clients and releases any
+	 * associated resources.
+	 */
+	default void close() {
+		this.closeGracefully().subscribe();
+	}
+
+	/**
+	 * Gracefully closes all the transports with connected clients and releases any
+	 * associated resources asynchronously.
+	 * @return a {@link Mono} that completes when the connections have been closed.
+	 */
+	Mono closeGracefully();
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
index 42d170db5..7b29ca651 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
@@ -5,6 +5,7 @@
 package io.modelcontextprotocol.spec;
 
 import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Mono;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
new file mode 100644
index 000000000..b6211fe3b
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
@@ -0,0 +1,25 @@
+package io.modelcontextprotocol.spec;
+
+import io.modelcontextprotocol.server.McpStatelessServerHandler;
+import reactor.core.publisher.Mono;
+
+public interface McpStatelessServerTransport {
+
+	void setMcpHandler(McpStatelessServerHandler mcpHandler);
+
+	/**
+	 * Immediately closes all the transports with connected clients and releases any
+	 * associated resources.
+	 */
+	default void close() {
+		this.closeGracefully().subscribe();
+	}
+
+	/**
+	 * Gracefully closes all the transports with connected clients and releases any
+	 * associated resources asynchronously.
+	 * @return a {@link Mono} that completes when the connections have been closed.
+	 */
+	Mono closeGracefully();
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
new file mode 100644
index 000000000..f600f28b3
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -0,0 +1,398 @@
+package io.modelcontextprotocol.spec;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.server.McpAsyncServerExchange;
+import io.modelcontextprotocol.server.McpNotificationHandler;
+import io.modelcontextprotocol.server.McpRequestHandler;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.util.Assert;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import reactor.core.publisher.MonoSink;
+
+import java.time.Duration;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Supplier;
+
+/**
+ * Representation of a Streamable HTTP server session that keeps track of mapping
+ * server-initiated requests to the client and mapping arriving responses. It also allows
+ * handling incoming notifications. For requests, it provides the default SSE streaming
+ * capability without the insight into the transport-specific details of HTTP handling.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class McpStreamableServerSession implements McpLoggableSession {
+
+	private static final Logger logger = LoggerFactory.getLogger(McpStreamableServerSession.class);
+
+	private final ConcurrentHashMap requestIdToStream = new ConcurrentHashMap<>();
+
+	private final String id;
+
+	private final Duration requestTimeout;
+
+	private final AtomicLong requestCounter = new AtomicLong(0);
+
+	private final Map> requestHandlers;
+
+	private final Map notificationHandlers;
+
+	private final AtomicReference clientCapabilities = new AtomicReference<>();
+
+	private final AtomicReference clientInfo = new AtomicReference<>();
+
+	private final AtomicReference listeningStreamRef;
+
+	private final MissingMcpTransportSession missingMcpTransportSession;
+
+	private volatile McpSchema.LoggingLevel minLoggingLevel = McpSchema.LoggingLevel.INFO;
+
+	/**
+	 * Create an instance of the streamable session.
+	 * @param id session ID
+	 * @param clientCapabilities client capabilities
+	 * @param clientInfo client info
+	 * @param requestTimeout timeout to use for requests
+	 * @param requestHandlers the map of MCP request handlers keyed by method name
+	 * @param notificationHandlers the map of MCP notification handlers keyed by method
+	 * name
+	 */
+	public McpStreamableServerSession(String id, McpSchema.ClientCapabilities clientCapabilities,
+			McpSchema.Implementation clientInfo, Duration requestTimeout,
+			Map> requestHandlers,
+			Map notificationHandlers) {
+		this.id = id;
+		this.missingMcpTransportSession = new MissingMcpTransportSession(id);
+		this.listeningStreamRef = new AtomicReference<>(this.missingMcpTransportSession);
+		this.clientCapabilities.lazySet(clientCapabilities);
+		this.clientInfo.lazySet(clientInfo);
+		this.requestTimeout = requestTimeout;
+		this.requestHandlers = requestHandlers;
+		this.notificationHandlers = notificationHandlers;
+	}
+
+	@Override
+	public void setMinLoggingLevel(McpSchema.LoggingLevel minLoggingLevel) {
+		Assert.notNull(minLoggingLevel, "minLoggingLevel must not be null");
+		this.minLoggingLevel = minLoggingLevel;
+	}
+
+	@Override
+	public boolean isNotificationForLevelAllowed(McpSchema.LoggingLevel loggingLevel) {
+		return loggingLevel.level() >= this.minLoggingLevel.level();
+	}
+
+	/**
+	 * Return the Session ID.
+	 * @return session ID
+	 */
+	public String getId() {
+		return this.id;
+	}
+
+	private String generateRequestId() {
+		return this.id + "-" + this.requestCounter.getAndIncrement();
+	}
+
+	@Override
+	public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+		return Mono.defer(() -> {
+			McpLoggableSession listeningStream = this.listeningStreamRef.get();
+			return listeningStream.sendRequest(method, requestParams, typeRef);
+		});
+	}
+
+	@Override
+	public Mono sendNotification(String method, Object params) {
+		return Mono.defer(() -> {
+			McpLoggableSession listeningStream = this.listeningStreamRef.get();
+			return listeningStream.sendNotification(method, params);
+		});
+	}
+
+	public Mono delete() {
+		return this.closeGracefully().then(Mono.fromRunnable(() -> {
+			// TODO: review in the context of history storage
+			// delete history, etc.
+		}));
+	}
+
+	/**
+	 * Create a listening stream (the generic HTTP GET request without Last-Event-ID
+	 * header).
+	 * @param transport The dedicated SSE transport stream
+	 * @return a stream representation
+	 */
+	public McpStreamableServerSessionStream listeningStream(McpStreamableServerTransport transport) {
+		McpStreamableServerSessionStream listeningStream = new McpStreamableServerSessionStream(transport);
+		this.listeningStreamRef.set(listeningStream);
+		return listeningStream;
+	}
+
+	// TODO: keep track of history by keeping a map from eventId to stream and then
+	// iterate over the events using the lastEventId
+	public Flux replay(Object lastEventId) {
+		return Flux.empty();
+	}
+
+	/**
+	 * Provide the SSE stream of MCP messages finalized with a Response.
+	 * @param jsonrpcRequest the MCP request triggering the stream creation
+	 * @param transport the SSE transport stream to send messages to
+	 * @return Mono which completes once the processing is done
+	 */
+	public Mono responseStream(McpSchema.JSONRPCRequest jsonrpcRequest, McpStreamableServerTransport transport) {
+		return Mono.deferContextual(ctx -> {
+			McpTransportContext transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+
+			McpStreamableServerSessionStream stream = new McpStreamableServerSessionStream(transport);
+			McpRequestHandler requestHandler = McpStreamableServerSession.this.requestHandlers
+				.get(jsonrpcRequest.method());
+			// TODO: delegate to stream, which upon successful response should close
+			// remove itself from the registry and also close the underlying transport
+			// (sink)
+			if (requestHandler == null) {
+				MethodNotFoundError error = getMethodNotFoundError(jsonrpcRequest.method());
+				return transport
+					.sendMessage(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), null,
+							new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.METHOD_NOT_FOUND,
+									error.message(), error.data())));
+			}
+			return requestHandler
+				.handle(new McpAsyncServerExchange(this.id, stream, clientCapabilities.get(), clientInfo.get(),
+						transportContext), jsonrpcRequest.params())
+				.map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), result,
+						null))
+				.onErrorResume(e -> {
+					var errorResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(),
+							null, new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
+									e.getMessage(), null));
+					return Mono.just(errorResponse);
+				})
+				.flatMap(transport::sendMessage)
+				.then(transport.closeGracefully());
+		});
+	}
+
+	/**
+	 * Handle the MCP notification.
+	 * @param notification MCP notification
+	 * @return Mono which completes upon succesful handling
+	 */
+	public Mono accept(McpSchema.JSONRPCNotification notification) {
+		return Mono.deferContextual(ctx -> {
+			McpTransportContext transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+			McpNotificationHandler notificationHandler = this.notificationHandlers.get(notification.method());
+			if (notificationHandler == null) {
+				logger.error("No handler registered for notification method: {}", notification.method());
+				return Mono.empty();
+			}
+			McpLoggableSession listeningStream = this.listeningStreamRef.get();
+			return notificationHandler.handle(new McpAsyncServerExchange(this.id, listeningStream,
+					this.clientCapabilities.get(), this.clientInfo.get(), transportContext), notification.params());
+		});
+
+	}
+
+	/**
+	 * Handle the MCP response.
+	 * @param response MCP response to the server-initiated request
+	 * @return Mono which completes upon successful processing
+	 */
+	public Mono accept(McpSchema.JSONRPCResponse response) {
+		return Mono.defer(() -> {
+			var stream = this.requestIdToStream.get(response.id());
+			if (stream == null) {
+				return Mono.error(new McpError("Unexpected response for unknown id " + response.id())); // TODO
+																										// JSONize
+			}
+			// TODO: encapsulate this inside the stream itself
+			var sink = stream.pendingResponses.remove(response.id());
+			if (sink == null) {
+				return Mono.error(new McpError("Unexpected response for unknown id " + response.id())); // TODO
+																										// JSONize
+			}
+			else {
+				sink.success(response);
+			}
+			return Mono.empty();
+		});
+	}
+
+	record MethodNotFoundError(String method, String message, Object data) {
+	}
+
+	private MethodNotFoundError getMethodNotFoundError(String method) {
+		return new MethodNotFoundError(method, "Method not found: " + method, null);
+	}
+
+	@Override
+	public Mono closeGracefully() {
+		return Mono.defer(() -> {
+			McpLoggableSession listeningStream = this.listeningStreamRef.getAndSet(missingMcpTransportSession);
+			return listeningStream.closeGracefully();
+			// TODO: Also close all the open streams
+		});
+	}
+
+	@Override
+	public void close() {
+		McpLoggableSession listeningStream = this.listeningStreamRef.getAndSet(missingMcpTransportSession);
+		if (listeningStream != null) {
+			listeningStream.close();
+		}
+		// TODO: Also close all open streams
+	}
+
+	/**
+	 * Request handler for the initialization request.
+	 */
+	public interface InitRequestHandler {
+
+		/**
+		 * Handles the initialization request.
+		 * @param initializeRequest the initialization request by the client
+		 * @return a Mono that will emit the result of the initialization
+		 */
+		Mono handle(McpSchema.InitializeRequest initializeRequest);
+
+	}
+
+	/**
+	 * Factory for new Streamable HTTP MCP sessions.
+	 */
+	public interface Factory {
+
+		/**
+		 * Given an initialize request, create a composite for the session initialization
+		 * @param initializeRequest the initialization request from the client
+		 * @return a composite allowing the session to start
+		 */
+		McpStreamableServerSessionInit startSession(McpSchema.InitializeRequest initializeRequest);
+
+	}
+
+	/**
+	 * Composite holding the {@link McpStreamableServerSession} and the initialization
+	 * result
+	 *
+	 * @param session the session instance
+	 * @param initResult the result to use to respond to the client
+	 */
+	public record McpStreamableServerSessionInit(McpStreamableServerSession session,
+			Mono initResult) {
+	}
+
+	/**
+	 * An individual SSE stream within a Streamable HTTP context. Can be either the
+	 * listening GET SSE stream or a request-specific POST SSE stream.
+	 */
+	public final class McpStreamableServerSessionStream implements McpLoggableSession {
+
+		private final ConcurrentHashMap> pendingResponses = new ConcurrentHashMap<>();
+
+		private final McpStreamableServerTransport transport;
+
+		private final String transportId;
+
+		private final Supplier uuidGenerator;
+
+		/**
+		 * Constructor accepting the dedicated transport representing the SSE stream.
+		 * @param transport request-specific SSE transport stream
+		 */
+		public McpStreamableServerSessionStream(McpStreamableServerTransport transport) {
+			this.transport = transport;
+			this.transportId = UUID.randomUUID().toString();
+			// This ID design allows for a constant-time extraction of the history by
+			// precisely identifying the SSE stream using the first component
+			this.uuidGenerator = () -> this.transportId + "_" + UUID.randomUUID();
+		}
+
+		@Override
+		public void setMinLoggingLevel(McpSchema.LoggingLevel minLoggingLevel) {
+			Assert.notNull(minLoggingLevel, "minLoggingLevel must not be null");
+			McpStreamableServerSession.this.setMinLoggingLevel(minLoggingLevel);
+		}
+
+		@Override
+		public boolean isNotificationForLevelAllowed(McpSchema.LoggingLevel loggingLevel) {
+			return McpStreamableServerSession.this.isNotificationForLevelAllowed(loggingLevel);
+		}
+
+		@Override
+		public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+			String requestId = McpStreamableServerSession.this.generateRequestId();
+
+			McpStreamableServerSession.this.requestIdToStream.put(requestId, this);
+
+			return Mono.create(sink -> {
+				this.pendingResponses.put(requestId, sink);
+				McpSchema.JSONRPCRequest jsonrpcRequest = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION,
+						method, requestId, requestParams);
+				String messageId = this.uuidGenerator.get();
+				// TODO: store message in history
+				this.transport.sendMessage(jsonrpcRequest, messageId).subscribe(v -> {
+				}, sink::error);
+			}).timeout(requestTimeout).doOnError(e -> {
+				this.pendingResponses.remove(requestId);
+				McpStreamableServerSession.this.requestIdToStream.remove(requestId);
+			}).handle((jsonRpcResponse, sink) -> {
+				if (jsonRpcResponse.error() != null) {
+					sink.error(new McpError(jsonRpcResponse.error()));
+				}
+				else {
+					if (typeRef.getType().equals(Void.class)) {
+						sink.complete();
+					}
+					else {
+						sink.next(this.transport.unmarshalFrom(jsonRpcResponse.result(), typeRef));
+					}
+				}
+			});
+		}
+
+		@Override
+		public Mono sendNotification(String method, Object params) {
+			McpSchema.JSONRPCNotification jsonrpcNotification = new McpSchema.JSONRPCNotification(
+					McpSchema.JSONRPC_VERSION, method, params);
+			String messageId = this.uuidGenerator.get();
+			// TODO: store message in history
+			return this.transport.sendMessage(jsonrpcNotification, messageId);
+		}
+
+		@Override
+		public Mono closeGracefully() {
+			return Mono.defer(() -> {
+				this.pendingResponses.values().forEach(s -> s.error(new RuntimeException("Stream closed")));
+				this.pendingResponses.clear();
+				// If this was the generic stream, reset it
+				McpStreamableServerSession.this.listeningStreamRef.compareAndExchange(this,
+						McpStreamableServerSession.this.missingMcpTransportSession);
+				McpStreamableServerSession.this.requestIdToStream.values().removeIf(this::equals);
+				return this.transport.closeGracefully();
+			});
+		}
+
+		@Override
+		public void close() {
+			this.pendingResponses.values().forEach(s -> s.error(new RuntimeException("Stream closed")));
+			this.pendingResponses.clear();
+			// If this was the generic stream, reset it
+			McpStreamableServerSession.this.listeningStreamRef.compareAndExchange(this,
+					McpStreamableServerSession.this.missingMcpTransportSession);
+			McpStreamableServerSession.this.requestIdToStream.values().removeIf(this::equals);
+			this.transport.close();
+		}
+
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
new file mode 100644
index 000000000..39e90ce86
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
@@ -0,0 +1,20 @@
+package io.modelcontextprotocol.spec;
+
+import reactor.core.publisher.Mono;
+
+/**
+ * Streamable HTTP server transport representing an individual SSE stream.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpStreamableServerTransport extends McpServerTransport {
+
+	/**
+	 * Send a message to the client with a message ID for use in the SSE event payload
+	 * @param message the JSON-RPC payload
+	 * @param messageId message id for SSE events
+	 * @return Mono which completes when done
+	 */
+	Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
new file mode 100644
index 000000000..87574e8ab
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
@@ -0,0 +1,67 @@
+package io.modelcontextprotocol.spec;
+
+import reactor.core.publisher.Mono;
+
+import java.util.Map;
+
+/**
+ * The core building block providing the server-side MCP transport for Streamable HTTP
+ * servers. Implement this interface to bridge between a particular server-side technology
+ * and the MCP server transport layer.
+ *
+ * 

+ * The lifecycle of the provider dictates that it be created first, upon application
+ * startup, and then passed into either
+ * {@link io.modelcontextprotocol.server.McpServer#sync(McpStreamableServerTransportProvider)}
+ * or
+ * {@link io.modelcontextprotocol.server.McpServer#async(McpStreamableServerTransportProvider)}.
+ * As a result of the MCP server creation, the provider will be notified of a
+ * {@link McpStreamableServerSession.Factory} which will be used to handle a 1:1
+ * communication between a newly connected client and the server using a session concept.
+ * The provider's responsibility is to create instances of
+ * {@link McpStreamableServerTransport} that the session will utilise during the session
+ * lifetime.
+ *
+ * 

+ * Finally, the {@link McpStreamableServerTransport}s can be closed in bulk when
+ * {@link #close()} or {@link #closeGracefully()} are called as part of the normal
+ * application shutdown event. Individual {@link McpStreamableServerTransport}s can also
+ * be closed on a per-session basis, where the {@link McpServerSession#close()} or
+ * {@link McpServerSession#closeGracefully()} closes the provided transport.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public interface McpStreamableServerTransportProvider extends McpServerTransportProviderBase {
+
+	/**
+	 * Sets the session factory that will be used to create sessions for new clients. An
+	 * implementation of the MCP server MUST call this method before any MCP interactions
+	 * take place.
+	 * @param sessionFactory the session factory to be used for initiating client sessions
+	 */
+	void setSessionFactory(McpStreamableServerSession.Factory sessionFactory);
+
+	/**
+	 * Sends a notification to all connected clients.
+	 * @param method the name of the notification method to be called on the clients
+	 * @param params parameters to be sent with the notification
+	 * @return a Mono that completes when the notification has been broadcast
+	 */
+	Mono notifyClients(String method, Object params);
+
+	/**
+	 * Immediately closes all the transports with connected clients and releases any
+	 * associated resources.
+	 */
+	default void close() {
+		this.closeGracefully().subscribe();
+	}
+
+	/**
+	 * Gracefully closes all the transports with connected clients and releases any
+	 * associated resources asynchronously.
+	 * @return a {@link Mono} that completes when the connections have been closed.
+	 */
+	Mono closeGracefully();
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
new file mode 100644
index 000000000..c83f0bead
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
@@ -0,0 +1,59 @@
+package io.modelcontextprotocol.spec;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.util.Assert;
+import reactor.core.publisher.Mono;
+
+/**
+ * A {@link McpLoggableSession} which represents a missing stream that would allow the
+ * server to communicate with the client. Specifically, it can be used when a Streamable
+ * HTTP client has not opened a listening SSE stream to accept messages for interactions
+ * unrelated with concurrently running client-initiated requests.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public class MissingMcpTransportSession implements McpLoggableSession {
+
+	private final String sessionId;
+
+	private volatile McpSchema.LoggingLevel minLoggingLevel = McpSchema.LoggingLevel.INFO;
+
+	/**
+	 * Create an instance with the Session ID specified.
+	 * @param sessionId session ID
+	 */
+	public MissingMcpTransportSession(String sessionId) {
+		this.sessionId = sessionId;
+	}
+
+	@Override
+	public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+		return Mono.error(new IllegalStateException("Stream unavailable for session " + this.sessionId));
+	}
+
+	@Override
+	public Mono sendNotification(String method, Object params) {
+		return Mono.error(new IllegalStateException("Stream unavailable for session " + this.sessionId));
+	}
+
+	@Override
+	public Mono closeGracefully() {
+		return Mono.empty();
+	}
+
+	@Override
+	public void close() {
+	}
+
+	@Override
+	public void setMinLoggingLevel(McpSchema.LoggingLevel minLoggingLevel) {
+		Assert.notNull(minLoggingLevel, "minLoggingLevel must not be null");
+		this.minLoggingLevel = minLoggingLevel;
+	}
+
+	@Override
+	public boolean isNotificationForLevelAllowed(McpSchema.LoggingLevel loggingLevel) {
+		return loggingLevel.level() >= this.minLoggingLevel.level();
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
index a101f0177..e9356d0c0 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
@@ -37,7 +37,7 @@ protected McpClientTransport createMcpTransport() {
 	}
 
 	protected Duration getInitializationTimeout() {
-		return Duration.ofSeconds(10);
+		return Duration.ofSeconds(20);
 	}
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index b5841e755..7a1e90770 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -21,6 +21,8 @@
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
@@ -43,7 +45,7 @@ public abstract class AbstractMcpAsyncServerTests {
 
 	private static final String TEST_PROMPT_NAME = "test-prompt";
 
-	abstract protected McpServerTransportProvider createMcpTransportProvider();
+	abstract protected McpServer.AsyncSpecification prepareAsyncServerBuilder();
 
 	protected void onStart() {
 	}
@@ -64,28 +66,29 @@ void tearDown() {
 	// Server Lifecycle Tests
 	// ---------------------------------------
 
-	@Test
-	void testConstructorWithInvalidArguments() {
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "sse", "streamable" })
+	void testConstructorWithInvalidArguments(String serverType) {
 		assertThatThrownBy(() -> McpServer.async((McpServerTransportProvider) null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Transport provider must not be null");
 
-		assertThatThrownBy(
-				() -> McpServer.async(createMcpTransportProvider()).serverInfo((McpSchema.Implementation) null))
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo((McpSchema.Implementation) null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Server info must not be null");
 	}
 
 	@Test
 	void testGracefulShutdown() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		McpServer.AsyncSpecification builder = prepareAsyncServerBuilder();
+		var mcpAsyncServer = builder.serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(mcpAsyncServer.closeGracefully()).verifyComplete();
 	}
 
 	@Test
 	void testImmediateClose() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpAsyncServer.close()).doesNotThrowAnyException();
 	}
@@ -105,8 +108,7 @@ void testImmediateClose() {
 	@Deprecated
 	void testAddTool() {
 		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -120,8 +122,7 @@ void testAddTool() {
 	@Test
 	void testAddToolCall() {
 		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -138,8 +139,7 @@ void testAddToolCall() {
 	void testAddDuplicateTool() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tool(duplicateTool, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -159,8 +159,7 @@ void testAddDuplicateTool() {
 	void testAddDuplicateToolCall() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -181,8 +180,7 @@ void testDuplicateToolCallDuringBuilding() {
 		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
 				emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) // Duplicate!
@@ -204,8 +202,7 @@ void testDuplicateToolsInBatchListRegistration() {
 					.build() // Duplicate!
 		);
 
-		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(specs)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -216,8 +213,7 @@ void testDuplicateToolsInBatchListRegistration() {
 	void testDuplicateToolsInBatchVarargsRegistration() {
 		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.AsyncToolSpecification.builder()
 				.tool(duplicateTool)
@@ -236,8 +232,7 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 	void testRemoveTool() {
 		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -249,8 +244,7 @@ void testRemoveTool() {
 
 	@Test
 	void testRemoveNonexistentTool() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -265,8 +259,7 @@ void testRemoveNonexistentTool() {
 	void testNotifyToolsListChanged() {
 		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
@@ -282,7 +275,7 @@ void testNotifyToolsListChanged() {
 
 	@Test
 	void testNotifyResourcesListChanged() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(mcpAsyncServer.notifyResourcesListChanged()).verifyComplete();
 
@@ -291,7 +284,7 @@ void testNotifyResourcesListChanged() {
 
 	@Test
 	void testNotifyResourcesUpdated() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier
 			.create(mcpAsyncServer
@@ -303,8 +296,7 @@ void testNotifyResourcesUpdated() {
 
 	@Test
 	void testAddResource() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -320,8 +312,7 @@ void testAddResource() {
 
 	@Test
 	void testAddResourceWithNullSpecification() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -336,9 +327,7 @@ void testAddResourceWithNullSpecification() {
 	@Test
 	void testAddResourceWithoutCapability() {
 		// Create a server without resource capabilities
-		McpAsyncServer serverWithoutResources = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
 				null);
@@ -354,9 +343,7 @@ void testAddResourceWithoutCapability() {
 	@Test
 	void testRemoveResourceWithoutCapability() {
 		// Create a server without resource capabilities
-		McpAsyncServer serverWithoutResources = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutResources.removeResource(TEST_RESOURCE_URI)).verifyErrorSatisfies(error -> {
 			assertThat(error).isInstanceOf(McpError.class)
@@ -370,7 +357,7 @@ void testRemoveResourceWithoutCapability() {
 
 	@Test
 	void testNotifyPromptsListChanged() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(mcpAsyncServer.notifyPromptsListChanged()).verifyComplete();
 
@@ -379,8 +366,7 @@ void testNotifyPromptsListChanged() {
 
 	@Test
 	void testAddPromptWithNullSpecification() {
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(false).build())
 			.build();
 
@@ -393,9 +379,7 @@ void testAddPromptWithNullSpecification() {
 	@Test
 	void testAddPromptWithoutCapability() {
 		// Create a server without prompt capabilities
-		McpAsyncServer serverWithoutPrompts = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutPrompts = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of());
 		McpServerFeatures.AsyncPromptSpecification specification = new McpServerFeatures.AsyncPromptSpecification(
@@ -411,9 +395,7 @@ void testAddPromptWithoutCapability() {
 	@Test
 	void testRemovePromptWithoutCapability() {
 		// Create a server without prompt capabilities
-		McpAsyncServer serverWithoutPrompts = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		McpAsyncServer serverWithoutPrompts = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).verifyErrorSatisfies(error -> {
 			assertThat(error).isInstanceOf(McpError.class)
@@ -430,8 +412,7 @@ void testRemovePrompt() {
 				prompt, (exchange, req) -> Mono.just(new GetPromptResult("Test prompt description", List
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))));
 
-		var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.prompts(specification)
 			.build();
@@ -443,8 +424,7 @@ void testRemovePrompt() {
 
 	@Test
 	void testRemoveNonexistentPrompt() {
-		var mcpAsyncServer2 = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpAsyncServer2 = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
@@ -467,8 +447,7 @@ void testRootsChangeHandlers() {
 		var rootsReceived = new McpSchema.Root[1];
 		var consumerCalled = new boolean[1];
 
-		var singleConsumerServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var singleConsumerServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> Mono.fromRunnable(() -> {
 				consumerCalled[0] = true;
 				if (!roots.isEmpty()) {
@@ -487,8 +466,7 @@ void testRootsChangeHandlers() {
 		var consumer2Called = new boolean[1];
 		var rootsContent = new List[1];
 
-		var multipleConsumersServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var multipleConsumersServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> Mono.fromRunnable(() -> {
 				consumer1Called[0] = true;
 				rootsContent[0] = roots;
@@ -501,8 +479,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test error handling
-		var errorHandlingServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var errorHandlingServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				throw new RuntimeException("Test error");
 			}))
@@ -514,9 +491,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test without consumers
-		var noConsumersServer = McpServer.async(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var noConsumersServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(noConsumersServer).isNotNull();
 		assertThatCode(() -> noConsumersServer.closeGracefully().block(Duration.ofSeconds(10)))
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 208d2e749..67579ce72 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -28,7 +28,7 @@
 
 /**
  * Test suite for the {@link McpSyncServer} that can be used with different
- * {@link McpTransportProvider} implementations.
+ * {@link McpServerTransportProvider} implementations.
  *
  * @author Christian Tzolov
  */
@@ -41,7 +41,7 @@ public abstract class AbstractMcpSyncServerTests {
 
 	private static final String TEST_PROMPT_NAME = "test-prompt";
 
-	abstract protected McpServerTransportProvider createMcpTransportProvider();
+	abstract protected McpServer.SyncSpecification prepareSyncServerBuilder();
 
 	protected void onStart() {
 	}
@@ -69,28 +69,28 @@ void testConstructorWithInvalidArguments() {
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Transport provider must not be null");
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider()).serverInfo(null))
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo(null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Server info must not be null");
 	}
 
 	@Test
 	void testGracefulShutdown() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testImmediateClose() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.close()).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testGetAsyncServer() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(mcpSyncServer.getAsyncServer()).isNotNull();
 
@@ -112,8 +112,7 @@ void testGetAsyncServer() {
 	@Test
 	@Deprecated
 	void testAddTool() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -127,8 +126,7 @@ void testAddTool() {
 
 	@Test
 	void testAddToolCall() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -146,8 +144,7 @@ void testAddToolCall() {
 	void testAddDuplicateTool() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tool(duplicateTool, (exchange, args) -> new CallToolResult(List.of(), false))
 			.build();
@@ -164,8 +161,7 @@ void testAddDuplicateTool() {
 	void testAddDuplicateToolCall() {
 		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
 			.build();
@@ -184,8 +180,7 @@ void testDuplicateToolCallDuringBuilding() {
 		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
 				emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) // Duplicate!
@@ -207,8 +202,7 @@ void testDuplicateToolsInBatchListRegistration() {
 					.build() // Duplicate!
 		);
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(specs)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -219,8 +213,7 @@ void testDuplicateToolsInBatchListRegistration() {
 	void testDuplicateToolsInBatchVarargsRegistration() {
 		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
 
-		assertThatThrownBy(() -> McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.SyncToolSpecification.builder()
 				.tool(duplicateTool)
@@ -239,8 +232,7 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 	void testRemoveTool() {
 		Tool tool = new McpSchema.Tool(TEST_TOOL_NAME, "Test tool", emptyJsonSchema);
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(tool, (exchange, args) -> new CallToolResult(List.of(), false))
 			.build();
@@ -252,8 +244,7 @@ void testRemoveTool() {
 
 	@Test
 	void testRemoveNonexistentTool() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
@@ -265,7 +256,7 @@ void testRemoveNonexistentTool() {
 
 	@Test
 	void testNotifyToolsListChanged() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.notifyToolsListChanged()).doesNotThrowAnyException();
 
@@ -278,7 +269,7 @@ void testNotifyToolsListChanged() {
 
 	@Test
 	void testNotifyResourcesListChanged() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.notifyResourcesListChanged()).doesNotThrowAnyException();
 
@@ -287,7 +278,7 @@ void testNotifyResourcesListChanged() {
 
 	@Test
 	void testNotifyResourcesUpdated() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer
 			.notifyResourcesUpdated(new McpSchema.ResourcesUpdatedNotification(TEST_RESOURCE_URI)))
@@ -298,8 +289,7 @@ void testNotifyResourcesUpdated() {
 
 	@Test
 	void testAddResource() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -315,8 +305,7 @@ void testAddResource() {
 
 	@Test
 	void testAddResourceWithNullSpecification() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
@@ -329,9 +318,7 @@ void testAddResourceWithNullSpecification() {
 
 	@Test
 	void testAddResourceWithoutCapability() {
-		var serverWithoutResources = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
 				null);
@@ -344,9 +331,7 @@ void testAddResourceWithoutCapability() {
 
 	@Test
 	void testRemoveResourceWithoutCapability() {
-		var serverWithoutResources = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI)).isInstanceOf(McpError.class)
 			.hasMessage("Server must be configured with resource capabilities");
@@ -358,7 +343,7 @@ void testRemoveResourceWithoutCapability() {
 
 	@Test
 	void testNotifyPromptsListChanged() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatCode(() -> mcpSyncServer.notifyPromptsListChanged()).doesNotThrowAnyException();
 
@@ -367,8 +352,7 @@ void testNotifyPromptsListChanged() {
 
 	@Test
 	void testAddPromptWithNullSpecification() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(false).build())
 			.build();
 
@@ -379,9 +363,7 @@ void testAddPromptWithNullSpecification() {
 
 	@Test
 	void testAddPromptWithoutCapability() {
-		var serverWithoutPrompts = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutPrompts = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		Prompt prompt = new Prompt(TEST_PROMPT_NAME, "Test Prompt", "Test Prompt", List.of());
 		McpServerFeatures.SyncPromptSpecification specification = new McpServerFeatures.SyncPromptSpecification(prompt,
@@ -394,9 +376,7 @@ void testAddPromptWithoutCapability() {
 
 	@Test
 	void testRemovePromptWithoutCapability() {
-		var serverWithoutPrompts = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
-			.build();
+		var serverWithoutPrompts = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).isInstanceOf(McpError.class)
 			.hasMessage("Server must be configured with prompt capabilities");
@@ -409,8 +389,7 @@ void testRemovePrompt() {
 				(exchange, req) -> new GetPromptResult("Test prompt description", List
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))));
 
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.prompts(specification)
 			.build();
@@ -422,8 +401,7 @@ void testRemovePrompt() {
 
 	@Test
 	void testRemoveNonexistentPrompt() {
-		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
@@ -443,8 +421,7 @@ void testRootsChangeHandlers() {
 		var rootsReceived = new McpSchema.Root[1];
 		var consumerCalled = new boolean[1];
 
-		var singleConsumerServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var singleConsumerServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				consumerCalled[0] = true;
 				if (!roots.isEmpty()) {
@@ -462,8 +439,7 @@ void testRootsChangeHandlers() {
 		var consumer2Called = new boolean[1];
 		var rootsContent = new List[1];
 
-		var multipleConsumersServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var multipleConsumersServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				consumer1Called[0] = true;
 				rootsContent[0] = roots;
@@ -475,8 +451,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test error handling
-		var errorHandlingServer = McpServer.sync(createMcpTransportProvider())
-			.serverInfo("test-server", "1.0.0")
+		var errorHandlingServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.rootsChangeHandlers(List.of((exchange, roots) -> {
 				throw new RuntimeException("Test error");
 			}))
@@ -487,7 +462,7 @@ void testRootsChangeHandlers() {
 		onClose();
 
 		// Test without consumers
-		var noConsumersServer = McpServer.sync(createMcpTransportProvider()).serverInfo("test-server", "1.0.0").build();
+		var noConsumersServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(noConsumersServer).isNotNull();
 		assertThatCode(() -> noConsumersServer.closeGracefully()).doesNotThrowAnyException();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
index 39066a9a2..987c43663 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
@@ -25,7 +25,6 @@
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.never;
-import static org.mockito.Mockito.reset;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -54,7 +53,8 @@ void setUp() {
 
 		clientInfo = new McpSchema.Implementation("test-client", "1.0.0");
 
-		exchange = new McpAsyncServerExchange(mockSession, clientCapabilities, clientInfo);
+		exchange = new McpAsyncServerExchange("testSessionId", mockSession, clientCapabilities, clientInfo,
+				new DefaultMcpTransportContext());
 	}
 
 	@Test
@@ -219,27 +219,33 @@ void testLoggingNotificationWithNullMessage() {
 	}
 
 	@Test
-	void testLoggingNotificationWithAllowedLevel() {
+	void testSetMinLoggingLevelWithNullValue() {
+		assertThatThrownBy(() -> exchange.setMinLoggingLevel(null)).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("minLoggingLevel must not be null");
+	}
 
+	@Test
+	void testLoggingNotificationWithAllowedLevel() {
 		McpSchema.LoggingMessageNotification notification = McpSchema.LoggingMessageNotification.builder()
 			.level(McpSchema.LoggingLevel.ERROR)
 			.logger("test-logger")
 			.data("Test error message")
 			.build();
 
+		when(mockSession.isNotificationForLevelAllowed(any())).thenReturn(Boolean.TRUE);
 		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification)))
 			.thenReturn(Mono.empty());
 
 		StepVerifier.create(exchange.loggingNotification(notification)).verifyComplete();
 
-		// Verify that sendNotification was called exactly once
+		verify(mockSession, times(1)).isNotificationForLevelAllowed(eq(McpSchema.LoggingLevel.ERROR));
 		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification));
 	}
 
 	@Test
 	void testLoggingNotificationWithFilteredLevel() {
-		// Given - Set minimum level to WARNING, send DEBUG message
-		exchange.setMinLoggingLevel(McpSchema.LoggingLevel.WARNING);
+		exchange.setMinLoggingLevel(McpSchema.LoggingLevel.DEBUG);
+		verify(mockSession, times(1)).setMinLoggingLevel(eq(McpSchema.LoggingLevel.DEBUG));
 
 		McpSchema.LoggingMessageNotification debugNotification = McpSchema.LoggingMessageNotification.builder()
 			.level(McpSchema.LoggingLevel.DEBUG)
@@ -247,104 +253,38 @@ void testLoggingNotificationWithFilteredLevel() {
 			.data("Debug message that should be filtered")
 			.build();
 
-		// When & Then - Should complete without sending notification
-		StepVerifier.create(exchange.loggingNotification(debugNotification)).verifyComplete();
-
-		// Verify that sendNotification was never called for filtered DEBUG level
-		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(debugNotification));
-	}
-
-	@Test
-	void testLoggingNotificationLevelFiltering() {
-		// Given - Set minimum level to WARNING
-		exchange.setMinLoggingLevel(McpSchema.LoggingLevel.WARNING);
-
-		// Test DEBUG (should be filtered)
-		McpSchema.LoggingMessageNotification debugNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.DEBUG)
-			.logger("test-logger")
-			.data("Debug message")
-			.build();
+		when(mockSession.isNotificationForLevelAllowed(eq(McpSchema.LoggingLevel.DEBUG))).thenReturn(Boolean.TRUE);
+		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(debugNotification)))
+			.thenReturn(Mono.empty());
 
 		StepVerifier.create(exchange.loggingNotification(debugNotification)).verifyComplete();
 
-		// Verify that sendNotification was never called for DEBUG level
-		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(debugNotification));
-
-		// Test INFO (should be filtered)
-		McpSchema.LoggingMessageNotification infoNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.INFO)
-			.logger("test-logger")
-			.data("Info message")
-			.build();
-
-		StepVerifier.create(exchange.loggingNotification(infoNotification)).verifyComplete();
-
-		// Verify that sendNotification was never called for INFO level
-		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(infoNotification));
-
-		reset(mockSession);
+		verify(mockSession, times(1)).isNotificationForLevelAllowed(eq(McpSchema.LoggingLevel.DEBUG));
+		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
+				eq(debugNotification));
 
-		// Test WARNING (should be sent)
 		McpSchema.LoggingMessageNotification warningNotification = McpSchema.LoggingMessageNotification.builder()
 			.level(McpSchema.LoggingLevel.WARNING)
 			.logger("test-logger")
-			.data("Warning message")
+			.data("Debug message that should be filtered")
 			.build();
 
-		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(warningNotification)))
-			.thenReturn(Mono.empty());
-
 		StepVerifier.create(exchange.loggingNotification(warningNotification)).verifyComplete();
 
-		// Verify that sendNotification was called exactly once for WARNING level
-		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
+		verify(mockSession, times(1)).isNotificationForLevelAllowed(eq(McpSchema.LoggingLevel.WARNING));
+		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
 				eq(warningNotification));
-
-		// Test ERROR (should be sent)
-		McpSchema.LoggingMessageNotification errorNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.ERROR)
-			.logger("test-logger")
-			.data("Error message")
-			.build();
-
-		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(errorNotification)))
-			.thenReturn(Mono.empty());
-
-		StepVerifier.create(exchange.loggingNotification(errorNotification)).verifyComplete();
-
-		// Verify that sendNotification was called exactly once for ERROR level
-		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
-				eq(errorNotification));
-	}
-
-	@Test
-	void testLoggingNotificationWithDefaultLevel() {
-
-		McpSchema.LoggingMessageNotification infoNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.INFO)
-			.logger("test-logger")
-			.data("Info message")
-			.build();
-
-		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(infoNotification)))
-			.thenReturn(Mono.empty());
-
-		StepVerifier.create(exchange.loggingNotification(infoNotification)).verifyComplete();
-
-		// Verify that sendNotification was called exactly once for default level
-		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(infoNotification));
 	}
 
 	@Test
 	void testLoggingNotificationWithSessionError() {
-
 		McpSchema.LoggingMessageNotification notification = McpSchema.LoggingMessageNotification.builder()
 			.level(McpSchema.LoggingLevel.ERROR)
 			.logger("test-logger")
 			.data("Test error message")
 			.build();
 
+		when(mockSession.isNotificationForLevelAllowed(any())).thenReturn(Boolean.TRUE);
 		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification)))
 			.thenReturn(Mono.error(new RuntimeException("Session error")));
 
@@ -353,44 +293,6 @@ void testLoggingNotificationWithSessionError() {
 		});
 	}
 
-	@Test
-	void testSetMinLoggingLevelWithNullValue() {
-		// When & Then
-		assertThatThrownBy(() -> exchange.setMinLoggingLevel(null)).isInstanceOf(IllegalArgumentException.class)
-			.hasMessage("minLoggingLevel must not be null");
-	}
-
-	@Test
-	void testLoggingLevelHierarchy() {
-		// Test all logging levels to ensure proper hierarchy
-		McpSchema.LoggingLevel[] levels = { McpSchema.LoggingLevel.DEBUG, McpSchema.LoggingLevel.INFO,
-				McpSchema.LoggingLevel.NOTICE, McpSchema.LoggingLevel.WARNING, McpSchema.LoggingLevel.ERROR,
-				McpSchema.LoggingLevel.CRITICAL, McpSchema.LoggingLevel.ALERT, McpSchema.LoggingLevel.EMERGENCY };
-
-		// Set minimum level to WARNING
-		exchange.setMinLoggingLevel(McpSchema.LoggingLevel.WARNING);
-
-		for (McpSchema.LoggingLevel level : levels) {
-			McpSchema.LoggingMessageNotification notification = McpSchema.LoggingMessageNotification.builder()
-				.level(level)
-				.logger("test-logger")
-				.data("Test message for " + level)
-				.build();
-
-			if (level.level() >= McpSchema.LoggingLevel.WARNING.level()) {
-				// Should be sent
-				when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification)))
-					.thenReturn(Mono.empty());
-
-				StepVerifier.create(exchange.loggingNotification(notification)).verifyComplete();
-			}
-			else {
-				// Should be filtered (completes without sending)
-				StepVerifier.create(exchange.loggingNotification(notification)).verifyComplete();
-			}
-		}
-	}
-
 	// ---------------------------------------
 	// Create Elicitation Tests
 	// ---------------------------------------
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
index 26b75946b..e6e80efb0 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
@@ -41,6 +41,8 @@ class McpCompletionTests {
 
 	private HttpServletSseServerTransportProvider mcpServerTransportProvider;
 
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
 	private static final String CUSTOM_MESSAGE_ENDPOINT = "/otherPath/mcp/message";
 
 	McpClient.SyncSpec clientBuilder;
@@ -55,7 +57,7 @@ public void before() {
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.build();
 
-		tomcat = TomcatTestUtil.createTomcatServer("", 3400, mcpServerTransportProvider);
+		tomcat = TomcatTestUtil.createTomcatServer("", PORT, mcpServerTransportProvider);
 		try {
 			tomcat.start();
 			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
@@ -64,7 +66,7 @@ public void before() {
 			throw new RuntimeException("Failed to start Tomcat", e);
 		}
 
-		this.clientBuilder = McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + 3400).build());
+		this.clientBuilder = McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT).build());
 	}
 
 	@AfterEach
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
index 66d7695e8..63d827013 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
@@ -226,19 +226,21 @@ void testLoggingNotificationWithAllowedLevel() {
 			.data("Test error message")
 			.build();
 
+		when(mockSession.isNotificationForLevelAllowed(any())).thenReturn(Boolean.TRUE);
 		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification)))
 			.thenReturn(Mono.empty());
 
 		exchange.loggingNotification(notification);
 
 		// Verify that sendNotification was called exactly once
+		verify(mockSession, times(1)).isNotificationForLevelAllowed(eq(McpSchema.LoggingLevel.ERROR));
 		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification));
 	}
 
 	@Test
 	void testLoggingNotificationWithFilteredLevel() {
-		// Given - Set minimum level to WARNING, send DEBUG message
-		asyncExchange.setMinLoggingLevel(McpSchema.LoggingLevel.WARNING);
+		asyncExchange.setMinLoggingLevel(McpSchema.LoggingLevel.DEBUG);
+		verify(mockSession, times(1)).setMinLoggingLevel(McpSchema.LoggingLevel.DEBUG);
 
 		McpSchema.LoggingMessageNotification debugNotification = McpSchema.LoggingMessageNotification.builder()
 			.level(McpSchema.LoggingLevel.DEBUG)
@@ -246,93 +248,27 @@ void testLoggingNotificationWithFilteredLevel() {
 			.data("Debug message that should be filtered")
 			.build();
 
-		// When & Then - Should complete without sending notification
-		exchange.loggingNotification(debugNotification);
-
-		// Verify that sendNotification was never called for filtered DEBUG level
-		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(debugNotification));
-	}
-
-	@Test
-	void testLoggingNotificationLevelFiltering() {
-		// Given - Set minimum level to WARNING
-		asyncExchange.setMinLoggingLevel(McpSchema.LoggingLevel.WARNING);
-
-		// Test DEBUG (should be filtered)
-		McpSchema.LoggingMessageNotification debugNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.DEBUG)
-			.logger("test-logger")
-			.data("Debug message")
-			.build();
+		when(mockSession.isNotificationForLevelAllowed(eq(McpSchema.LoggingLevel.DEBUG))).thenReturn(Boolean.TRUE);
+		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(debugNotification)))
+			.thenReturn(Mono.empty());
 
 		exchange.loggingNotification(debugNotification);
 
-		// Verify that sendNotification was never called for DEBUG level
-		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(debugNotification));
-
-		// Test INFO (should be filtered)
-		McpSchema.LoggingMessageNotification infoNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.INFO)
-			.logger("test-logger")
-			.data("Info message")
-			.build();
-
-		exchange.loggingNotification(infoNotification);
-
-		// Verify that sendNotification was never called for INFO level
-		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(infoNotification));
-
-		reset(mockSession);
+		verify(mockSession, times(1)).isNotificationForLevelAllowed(McpSchema.LoggingLevel.DEBUG);
+		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
+				eq(debugNotification));
 
-		// Test WARNING (should be sent)
 		McpSchema.LoggingMessageNotification warningNotification = McpSchema.LoggingMessageNotification.builder()
 			.level(McpSchema.LoggingLevel.WARNING)
 			.logger("test-logger")
-			.data("Warning message")
+			.data("Debug message that should be filtered")
 			.build();
 
-		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(warningNotification)))
-			.thenReturn(Mono.empty());
-
 		exchange.loggingNotification(warningNotification);
 
-		// Verify that sendNotification was called exactly once for WARNING level
-		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
+		verify(mockSession, times(1)).isNotificationForLevelAllowed(McpSchema.LoggingLevel.WARNING);
+		verify(mockSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
 				eq(warningNotification));
-
-		// Test ERROR (should be sent)
-		McpSchema.LoggingMessageNotification errorNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.ERROR)
-			.logger("test-logger")
-			.data("Error message")
-			.build();
-
-		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(errorNotification)))
-			.thenReturn(Mono.empty());
-
-		exchange.loggingNotification(errorNotification);
-
-		// Verify that sendNotification was called exactly once for ERROR level
-		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE),
-				eq(errorNotification));
-	}
-
-	@Test
-	void testLoggingNotificationWithDefaultLevel() {
-
-		McpSchema.LoggingMessageNotification infoNotification = McpSchema.LoggingMessageNotification.builder()
-			.level(McpSchema.LoggingLevel.INFO)
-			.logger("test-logger")
-			.data("Info message")
-			.build();
-
-		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(infoNotification)))
-			.thenReturn(Mono.empty());
-
-		exchange.loggingNotification(infoNotification);
-
-		// Verify that sendNotification was called exactly once for default level
-		verify(mockSession, times(1)).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(infoNotification));
 	}
 
 	@Test
@@ -344,6 +280,7 @@ void testLoggingNotificationWithSessionError() {
 			.data("Test error message")
 			.build();
 
+		when(mockSession.isNotificationForLevelAllowed(any())).thenReturn(Boolean.TRUE);
 		when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification)))
 			.thenReturn(Mono.error(new RuntimeException("Session error")));
 
@@ -351,37 +288,6 @@ void testLoggingNotificationWithSessionError() {
 			.hasMessage("Session error");
 	}
 
-	@Test
-	void testLoggingLevelHierarchy() {
-		// Test all logging levels to ensure proper hierarchy
-		McpSchema.LoggingLevel[] levels = { McpSchema.LoggingLevel.DEBUG, McpSchema.LoggingLevel.INFO,
-				McpSchema.LoggingLevel.NOTICE, McpSchema.LoggingLevel.WARNING, McpSchema.LoggingLevel.ERROR,
-				McpSchema.LoggingLevel.CRITICAL, McpSchema.LoggingLevel.ALERT, McpSchema.LoggingLevel.EMERGENCY };
-
-		// Set minimum level to WARNING
-		asyncExchange.setMinLoggingLevel(McpSchema.LoggingLevel.WARNING);
-
-		for (McpSchema.LoggingLevel level : levels) {
-			McpSchema.LoggingMessageNotification notification = McpSchema.LoggingMessageNotification.builder()
-				.level(level)
-				.logger("test-logger")
-				.data("Test message for " + level)
-				.build();
-
-			if (level.level() >= McpSchema.LoggingLevel.WARNING.level()) {
-				// Should be sent
-				when(mockSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_MESSAGE), eq(notification)))
-					.thenReturn(Mono.empty());
-
-				exchange.loggingNotification(notification);
-			}
-			else {
-				// Should be filtered (completes without sending)
-				exchange.loggingNotification(notification);
-			}
-		}
-	}
-
 	// ---------------------------------------
 	// Create Elicitation Tests
 	// ---------------------------------------
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java
index 81d904292..8906adfe0 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java
@@ -16,9 +16,13 @@
 @Timeout(15) // Giving extra time beyond the client timeout
 class ServletSseMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
 
-	@Override
 	protected McpServerTransportProvider createMcpTransportProvider() {
 		return HttpServletSseServerTransportProvider.builder().messageEndpoint("/mcp/message").build();
 	}
 
+	@Override
+	protected McpServer.AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(createMcpTransportProvider());
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java
index 154cf3a61..7b77f9241 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java
@@ -16,9 +16,13 @@
 @Timeout(15) // Giving extra time beyond the client timeout
 class ServletSseMcpSyncServerTests extends AbstractMcpSyncServerTests {
 
-	@Override
 	protected McpServerTransportProvider createMcpTransportProvider() {
 		return HttpServletSseServerTransportProvider.builder().messageEndpoint("/mcp/message").build();
 	}
 
+	@Override
+	protected McpServer.SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(createMcpTransportProvider());
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
index 0381a43bd..97db5fa06 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
@@ -16,9 +16,13 @@
 @Timeout(15) // Giving extra time beyond the client timeout
 class StdioMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
 
-	@Override
 	protected McpServerTransportProvider createMcpTransportProvider() {
 		return new StdioServerTransportProvider();
 	}
 
+	@Override
+	protected McpServer.AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(createMcpTransportProvider());
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
index a71c38493..1e01962e9 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
@@ -16,9 +16,13 @@
 @Timeout(15) // Giving extra time beyond the client timeout
 class StdioMcpSyncServerTests extends AbstractMcpSyncServerTests {
 
-	@Override
 	protected McpServerTransportProvider createMcpTransportProvider() {
 		return new StdioServerTransportProvider();
 	}
 
+	@Override
+	protected McpServer.SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(createMcpTransportProvider());
+	}
+
 }

From 73515346ca901612562128ea5d53cb6c6fee5385 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Wed, 30 Jul 2025 14:38:16 +0200
Subject: [PATCH 020/125] feat: Add Spring WebMVC streamable server transport
 provider (#425)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add WebMvcStreamableServerTransportProvider with SSE support for streamable sessions
- Support GET, POST, DELETE endpoints for MCP protocol operations
- Implement thread-safe SSE operations using ReentrantLock in WebMvcSseServerTransportProvider
- Add test infrastructure with AbstractMcpClientServerIntegrationTests
  - Refactor WebMvcStreamableIntegrationTests to use parameterized tests
  - Support testing with both HttpClient and WebFlux transports
- Add streamable transport tests for both async and sync server modes
- Refactor existing WebMVC SSE integration tests to use shared test base
- Add error handling improvements in McpStreamableServerSession
- Update dependencies: add json-unit-assertj for enhanced JSON testing
- Reorganize POM dependencies and add mcp-spring-webflux test dependency
- Wrap handler invocations with Mono.defer for lazy evaluation
   - Wrap consumer, tool, resource, prompt, and completion handler calls with Mono.defer()
   - Ensures proper lazy evaluation and error handling in reactive streams

Related to #72

Signed-off-by: Christian Tzolov 
Signed-off-by: Dariusz Jędrzejczyk 
Co-authored-by: Dariusz Jędrzejczyk 
---
 mcp-spring/mcp-spring-webmvc/pom.xml          |   15 +-
 .../WebMvcSseServerTransportProvider.java     |   19 +
 ...bMvcStreamableServerTransportProvider.java |  654 +++++++++
 ...cpStreamableAsyncServerTransportTests.java |  121 ++
 ...McpStreamableSyncServerTransportTests.java |  121 ++
 .../server/WebMvcSseIntegrationTests.java     | 1161 +--------------
 .../WebMvcStreamableIntegrationTests.java     |  165 +++
 mcp-test/pom.xml                              |    7 +
 ...stractMcpClientServerIntegrationTests.java | 1274 +++++++++++++++++
 .../server/McpAsyncServer.java                |   10 +-
 .../server/AbstractMcpAsyncServerTests.java   |   22 +-
 11 files changed, 2410 insertions(+), 1159 deletions(-)
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
 create mode 100644 mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java

diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 4c6d37bf9..4b8c684ab 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -28,6 +28,12 @@
 			0.11.0-SNAPSHOT
 		
 
+		
+			org.springframework
+			spring-webmvc
+			${springframework.version}
+		
+
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
@@ -35,10 +41,11 @@
 			test
 		
 
-		
-			org.springframework
-			spring-webmvc
-			${springframework.version}
+				
+			io.modelcontextprotocol.sdk
+			mcp-spring-webflux
+			0.11.0-SNAPSHOT
+			test
 		
 
 
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index 114eff607..5aa89d529 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -8,6 +8,7 @@
 import java.time.Duration;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.locks.ReentrantLock;
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -339,6 +340,12 @@ private class WebMvcMcpSessionTransport implements McpServerTransport {
 
 		private final SseBuilder sseBuilder;
 
+		/**
+		 * Lock to ensure thread-safe access to the SSE builder when sending messages.
+		 * This prevents concurrent modifications that could lead to corrupted SSE events.
+		 */
+		private final ReentrantLock sseBuilderLock = new ReentrantLock();
+
 		/**
 		 * Creates a new session transport with the specified ID and SSE builder.
 		 * @param sessionId The unique identifier for this session
@@ -358,6 +365,7 @@ private class WebMvcMcpSessionTransport implements McpServerTransport {
 		@Override
 		public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			return Mono.fromRunnable(() -> {
+				sseBuilderLock.lock();
 				try {
 					String jsonText = objectMapper.writeValueAsString(message);
 					sseBuilder.id(sessionId).event(MESSAGE_EVENT_TYPE).data(jsonText);
@@ -367,6 +375,9 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 					logger.error("Failed to send message to session {}: {}", sessionId, e.getMessage());
 					sseBuilder.error(e);
 				}
+				finally {
+					sseBuilderLock.unlock();
+				}
 			});
 		}
 
@@ -390,6 +401,7 @@ public  T unmarshalFrom(Object data, TypeReference typeRef) {
 		public Mono closeGracefully() {
 			return Mono.fromRunnable(() -> {
 				logger.debug("Closing session transport: {}", sessionId);
+				sseBuilderLock.lock();
 				try {
 					sseBuilder.complete();
 					logger.debug("Successfully completed SSE builder for session {}", sessionId);
@@ -397,6 +409,9 @@ public Mono closeGracefully() {
 				catch (Exception e) {
 					logger.warn("Failed to complete SSE builder for session {}: {}", sessionId, e.getMessage());
 				}
+				finally {
+					sseBuilderLock.unlock();
+				}
 			});
 		}
 
@@ -405,6 +420,7 @@ public Mono closeGracefully() {
 		 */
 		@Override
 		public void close() {
+			sseBuilderLock.lock();
 			try {
 				sseBuilder.complete();
 				logger.debug("Successfully completed SSE builder for session {}", sessionId);
@@ -412,6 +428,9 @@ public void close() {
 			catch (Exception e) {
 				logger.warn("Failed to complete SSE builder for session {}: {}", sessionId, e.getMessage());
 			}
+			finally {
+				sseBuilderLock.unlock();
+			}
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
new file mode 100644
index 000000000..d14a51d87
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -0,0 +1,654 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server.transport;
+
+import java.io.IOException;
+import java.time.Duration;
+import java.util.List;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.locks.ReentrantLock;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.RouterFunctions;
+import org.springframework.web.servlet.function.ServerRequest;
+import org.springframework.web.servlet.function.ServerResponse;
+import org.springframework.web.servlet.function.ServerResponse.SseBuilder;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.spec.HttpHeaders;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpStreamableServerSession;
+import io.modelcontextprotocol.spec.McpStreamableServerTransport;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import io.modelcontextprotocol.util.Assert;
+import reactor.core.publisher.Mono;
+
+/**
+ * Server-side implementation of the Model Context Protocol (MCP) streamable transport
+ * layer using HTTP with Server-Sent Events (SSE) through Spring WebMVC. This
+ * implementation provides a bridge between synchronous WebMVC operations and reactive
+ * programming patterns to maintain compatibility with the reactive transport interface.
+ *
+ * 

+ * This is the non-reactive version of
+ * {@link io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider}
+ *
+ * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
+ * @see McpStreamableServerTransportProvider
+ * @see RouterFunction
+ */
+public class WebMvcStreamableServerTransportProvider implements McpStreamableServerTransportProvider {
+
+	private static final Logger logger = LoggerFactory.getLogger(WebMvcStreamableServerTransportProvider.class);
+
+	/**
+	 * Event type for JSON-RPC messages sent through the SSE connection.
+	 */
+	public static final String MESSAGE_EVENT_TYPE = "message";
+
+	/**
+	 * Event type for sending the message endpoint URI to clients.
+	 */
+	public static final String ENDPOINT_EVENT_TYPE = "endpoint";
+
+	/**
+	 * Default base URL for the message endpoint.
+	 */
+	public static final String DEFAULT_BASE_URL = "";
+
+	/**
+	 * The endpoint URI where clients should send their JSON-RPC messages. Defaults to
+	 * "/mcp".
+	 */
+	private final String mcpEndpoint;
+
+	/**
+	 * Flag indicating whether DELETE requests are disallowed on the endpoint.
+	 */
+	private final boolean disallowDelete;
+
+	private final ObjectMapper objectMapper;
+
+	private final RouterFunction routerFunction;
+
+	private McpStreamableServerSession.Factory sessionFactory;
+
+	/**
+	 * Map of active client sessions, keyed by mcp-session-id.
+	 */
+	private final ConcurrentHashMap sessions = new ConcurrentHashMap<>();
+
+	private McpTransportContextExtractor contextExtractor;
+
+	// private Function contextExtractor = req -> new
+	// DefaultMcpTransportContext();
+
+	/**
+	 * Flag indicating if the transport is shutting down.
+	 */
+	private volatile boolean isClosing = false;
+
+	/**
+	 * Constructs a new WebMvcStreamableServerTransportProvider instance.
+	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * of messages.
+	 * @param baseUrl The base URL for the message endpoint, used to construct the full
+	 * endpoint URL for clients.
+	 * @param mcpEndpoint The endpoint URI where clients should send their JSON-RPC
+	 * messages via HTTP. This endpoint will handle GET, POST, and DELETE requests.
+	 * @param disallowDelete Whether to disallow DELETE requests on the endpoint.
+	 * @throws IllegalArgumentException if any parameter is null
+	 */
+	private WebMvcStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
+			boolean disallowDelete, McpTransportContextExtractor contextExtractor) {
+		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
+		Assert.notNull(contextExtractor, "McpTransportContextExtractor must not be null");
+
+		this.objectMapper = objectMapper;
+		this.mcpEndpoint = mcpEndpoint;
+		this.disallowDelete = disallowDelete;
+		this.contextExtractor = contextExtractor;
+		this.routerFunction = RouterFunctions.route()
+			.GET(this.mcpEndpoint, this::handleGet)
+			.POST(this.mcpEndpoint, this::handlePost)
+			.DELETE(this.mcpEndpoint, this::handleDelete)
+			.build();
+	}
+
+	@Override
+	public void setSessionFactory(McpStreamableServerSession.Factory sessionFactory) {
+		this.sessionFactory = sessionFactory;
+	}
+
+	/**
+	 * Broadcasts a notification to all connected clients through their SSE connections.
+	 * If any errors occur during sending to a particular client, they are logged but
+	 * don't prevent sending to other clients.
+	 * @param method The method name for the notification
+	 * @param params The parameters for the notification
+	 * @return A Mono that completes when the broadcast attempt is finished
+	 */
+	@Override
+	public Mono notifyClients(String method, Object params) {
+		if (this.sessions.isEmpty()) {
+			logger.debug("No active sessions to broadcast message to");
+			return Mono.empty();
+		}
+
+		logger.debug("Attempting to broadcast message to {} active sessions", this.sessions.size());
+
+		return Mono.fromRunnable(() -> {
+			this.sessions.values().parallelStream().forEach(session -> {
+				try {
+					session.sendNotification(method, params).block();
+				}
+				catch (Exception e) {
+					logger.error("Failed to send message to session {}: {}", session.getId(), e.getMessage());
+				}
+			});
+		});
+	}
+
+	/**
+	 * Initiates a graceful shutdown of the transport.
+	 * @return A Mono that completes when all cleanup operations are finished
+	 */
+	@Override
+	public Mono closeGracefully() {
+		return Mono.fromRunnable(() -> {
+			this.isClosing = true;
+			logger.debug("Initiating graceful shutdown with {} active sessions", this.sessions.size());
+
+			this.sessions.values().parallelStream().forEach(session -> {
+				try {
+					session.closeGracefully().block();
+				}
+				catch (Exception e) {
+					logger.error("Failed to close session {}: {}", session.getId(), e.getMessage());
+				}
+			});
+
+			this.sessions.clear();
+			logger.debug("Graceful shutdown completed");
+		});
+	}
+
+	/**
+	 * Returns the RouterFunction that defines the HTTP endpoints for this transport. The
+	 * router function handles three endpoints:
+	 * 
    
+	 * 
  • GET [mcpEndpoint] - For establishing SSE connections and message replay
    • 
+	 * 
  • POST [mcpEndpoint] - For receiving JSON-RPC messages from clients
    • 
+	 * 
  • DELETE [mcpEndpoint] - For session deletion (if enabled)
    • 
+	 * 

+	 * @return The configured RouterFunction for handling HTTP requests
+	 */
+	public RouterFunction getRouterFunction() {
+		return this.routerFunction;
+	}
+
+	/**
+	 * Setup the listening SSE connections and message replay.
+	 * @param request The incoming server request
+	 * @return A ServerResponse configured for SSE communication, or an error response
+	 */
+	private ServerResponse handleGet(ServerRequest request) {
+		if (this.isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
+		}
+
+		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
+		if (!acceptHeaders.contains(MediaType.TEXT_EVENT_STREAM)) {
+			return ServerResponse.badRequest().body("Invalid Accept header. Expected TEXT_EVENT_STREAM");
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+			return ServerResponse.badRequest().body("Session ID required in mcp-session-id header");
+		}
+
+		String sessionId = request.headers().asHttpHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+		McpStreamableServerSession session = this.sessions.get(sessionId);
+
+		if (session == null) {
+			return ServerResponse.notFound().build();
+		}
+
+		logger.debug("Handling GET request for session: {}", sessionId);
+
+		try {
+			return ServerResponse.sse(sseBuilder -> {
+				sseBuilder.onTimeout(() -> {
+					logger.debug("SSE connection timed out for session: {}", sessionId);
+				});
+
+				WebMvcStreamableMcpSessionTransport sessionTransport = new WebMvcStreamableMcpSessionTransport(
+						sessionId, sseBuilder);
+
+				// Check if this is a replay request
+				if (request.headers().asHttpHeaders().containsKey(HttpHeaders.LAST_EVENT_ID)) {
+					String lastId = request.headers().asHttpHeaders().getFirst(HttpHeaders.LAST_EVENT_ID);
+
+					try {
+						session.replay(lastId)
+							.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+							.toIterable()
+							.forEach(message -> {
+								try {
+									sessionTransport.sendMessage(message)
+										.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+										.block();
+								}
+								catch (Exception e) {
+									logger.error("Failed to replay message: {}", e.getMessage());
+									sseBuilder.error(e);
+								}
+							});
+					}
+					catch (Exception e) {
+						logger.error("Failed to replay messages: {}", e.getMessage());
+						sseBuilder.error(e);
+					}
+				}
+				else {
+					// Establish new listening stream
+					McpStreamableServerSession.McpStreamableServerSessionStream listeningStream = session
+						.listeningStream(sessionTransport);
+
+					sseBuilder.onComplete(() -> {
+						logger.debug("SSE connection completed for session: {}", sessionId);
+						listeningStream.close();
+					});
+				}
+			}, Duration.ZERO);
+		}
+		catch (Exception e) {
+			logger.error("Failed to handle GET request for session {}: {}", sessionId, e.getMessage());
+			return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
+		}
+	}
+
+	/**
+	 * Handles POST requests for incoming JSON-RPC messages from clients.
+	 * @param request The incoming server request containing the JSON-RPC message
+	 * @return A ServerResponse indicating success or appropriate error status
+	 */
+	private ServerResponse handlePost(ServerRequest request) {
+		if (this.isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
+		}
+
+		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
+		if (!acceptHeaders.contains(MediaType.TEXT_EVENT_STREAM)
+				|| !acceptHeaders.contains(MediaType.APPLICATION_JSON)) {
+			return ServerResponse.badRequest()
+				.body(new McpError("Invalid Accept headers. Expected TEXT_EVENT_STREAM and APPLICATION_JSON"));
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		try {
+			String body = request.body(String.class);
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+
+			// Handle initialization request
+			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest
+					&& jsonrpcRequest.method().equals(McpSchema.METHOD_INITIALIZE)) {
+				McpSchema.InitializeRequest initializeRequest = objectMapper.convertValue(jsonrpcRequest.params(),
+						new TypeReference() {
+						});
+				McpStreamableServerSession.McpStreamableServerSessionInit init = this.sessionFactory
+					.startSession(initializeRequest);
+				this.sessions.put(init.session().getId(), init.session());
+
+				try {
+					McpSchema.InitializeResult initResult = init.initResult().block();
+
+					return ServerResponse.ok()
+						.contentType(MediaType.APPLICATION_JSON)
+						.header(HttpHeaders.MCP_SESSION_ID, init.session().getId())
+						.body(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), initResult,
+								null));
+				}
+				catch (Exception e) {
+					logger.error("Failed to initialize session: {}", e.getMessage());
+					return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).body(new McpError(e.getMessage()));
+				}
+			}
+
+			// Handle other messages that require a session
+			if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+				return ServerResponse.badRequest().body(new McpError("Session ID missing"));
+			}
+
+			String sessionId = request.headers().asHttpHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+			McpStreamableServerSession session = this.sessions.get(sessionId);
+
+			if (session == null) {
+				return ServerResponse.status(HttpStatus.NOT_FOUND)
+					.body(new McpError("Session not found: " + sessionId));
+			}
+
+			if (message instanceof McpSchema.JSONRPCResponse jsonrpcResponse) {
+				session.accept(jsonrpcResponse)
+					.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+					.block();
+				return ServerResponse.accepted().build();
+			}
+			else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
+				session.accept(jsonrpcNotification)
+					.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+					.block();
+				return ServerResponse.accepted().build();
+			}
+			else if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
+				// For streaming responses, we need to return SSE
+				return ServerResponse.sse(sseBuilder -> {
+					sseBuilder.onComplete(() -> {
+						logger.debug("Request response stream completed for session: {}", sessionId);
+					});
+					sseBuilder.onTimeout(() -> {
+						logger.debug("Request response stream timed out for session: {}", sessionId);
+					});
+
+					WebMvcStreamableMcpSessionTransport sessionTransport = new WebMvcStreamableMcpSessionTransport(
+							sessionId, sseBuilder);
+
+					try {
+						session.responseStream(jsonrpcRequest, sessionTransport)
+							.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+							.block();
+					}
+					catch (Exception e) {
+						logger.error("Failed to handle request stream: {}", e.getMessage());
+						sseBuilder.error(e);
+					}
+				}, Duration.ZERO);
+			}
+			else {
+				return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
+					.body(new McpError("Unknown message type"));
+			}
+		}
+		catch (IllegalArgumentException | IOException e) {
+			logger.error("Failed to deserialize message: {}", e.getMessage());
+			return ServerResponse.badRequest().body(new McpError("Invalid message format"));
+		}
+		catch (Exception e) {
+			logger.error("Error handling message: {}", e.getMessage());
+			return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).body(new McpError(e.getMessage()));
+		}
+	}
+
+	/**
+	 * Handles DELETE requests for session deletion.
+	 * @param request The incoming server request
+	 * @return A ServerResponse indicating success or appropriate error status
+	 */
+	private ServerResponse handleDelete(ServerRequest request) {
+		if (this.isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
+		}
+
+		if (this.disallowDelete) {
+			return ServerResponse.status(HttpStatus.METHOD_NOT_ALLOWED).build();
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+			return ServerResponse.badRequest().body("Session ID required in mcp-session-id header");
+		}
+
+		String sessionId = request.headers().asHttpHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+		McpStreamableServerSession session = this.sessions.get(sessionId);
+
+		if (session == null) {
+			return ServerResponse.notFound().build();
+		}
+
+		try {
+			session.delete().contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)).block();
+			this.sessions.remove(sessionId);
+			return ServerResponse.ok().build();
+		}
+		catch (Exception e) {
+			logger.error("Failed to delete session {}: {}", sessionId, e.getMessage());
+			return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).body(new McpError(e.getMessage()));
+		}
+	}
+
+	/**
+	 * Implementation of McpStreamableServerTransport for WebMVC SSE sessions. This class
+	 * handles the transport-level communication for a specific client session.
+	 *
+	 * 

+	 * This class is thread-safe and uses a ReentrantLock to synchronize access to the
+	 * underlying SSE builder to prevent race conditions when multiple threads attempt to
+	 * send messages concurrently.
+	 */
+	private class WebMvcStreamableMcpSessionTransport implements McpStreamableServerTransport {
+
+		private final String sessionId;
+
+		private final SseBuilder sseBuilder;
+
+		private final ReentrantLock lock = new ReentrantLock();
+
+		private volatile boolean closed = false;
+
+		/**
+		 * Creates a new session transport with the specified ID and SSE builder.
+		 * @param sessionId The unique identifier for this session
+		 * @param sseBuilder The SSE builder for sending server events to the client
+		 */
+		WebMvcStreamableMcpSessionTransport(String sessionId, SseBuilder sseBuilder) {
+			this.sessionId = sessionId;
+			this.sseBuilder = sseBuilder;
+			logger.debug("Streamable session transport {} initialized with SSE builder", sessionId);
+		}
+
+		/**
+		 * Sends a JSON-RPC message to the client through the SSE connection.
+		 * @param message The JSON-RPC message to send
+		 * @return A Mono that completes when the message has been sent
+		 */
+		@Override
+		public Mono sendMessage(McpSchema.JSONRPCMessage message) {
+			return sendMessage(message, null);
+		}
+
+		/**
+		 * Sends a JSON-RPC message to the client through the SSE connection with a
+		 * specific message ID.
+		 * @param message The JSON-RPC message to send
+		 * @param messageId The message ID for SSE event identification
+		 * @return A Mono that completes when the message has been sent
+		 */
+		@Override
+		public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId) {
+			return Mono.fromRunnable(() -> {
+				if (this.closed) {
+					logger.debug("Attempted to send message to closed session: {}", this.sessionId);
+					return;
+				}
+
+				this.lock.lock();
+				try {
+					if (this.closed) {
+						logger.debug("Session {} was closed during message send attempt", this.sessionId);
+						return;
+					}
+
+					String jsonText = objectMapper.writeValueAsString(message);
+					this.sseBuilder.id(messageId != null ? messageId : this.sessionId)
+						.event(MESSAGE_EVENT_TYPE)
+						.data(jsonText);
+					logger.debug("Message sent to session {} with ID {}", this.sessionId, messageId);
+				}
+				catch (Exception e) {
+					logger.error("Failed to send message to session {}: {}", this.sessionId, e.getMessage());
+					try {
+						this.sseBuilder.error(e);
+					}
+					catch (Exception errorException) {
+						logger.error("Failed to send error to SSE builder for session {}: {}", this.sessionId,
+								errorException.getMessage());
+					}
+				}
+				finally {
+					this.lock.unlock();
+				}
+			});
+		}
+
+		/**
+		 * Converts data from one type to another using the configured ObjectMapper.
+		 * @param data The source data object to convert
+		 * @param typeRef The target type reference
+		 * @return The converted object of type T
+		 * @param  The target type
+		 */
+		@Override
+		public  T unmarshalFrom(Object data, TypeReference typeRef) {
+			return objectMapper.convertValue(data, typeRef);
+		}
+
+		/**
+		 * Initiates a graceful shutdown of the transport.
+		 * @return A Mono that completes when the shutdown is complete
+		 */
+		@Override
+		public Mono closeGracefully() {
+			return Mono.fromRunnable(() -> {
+				WebMvcStreamableMcpSessionTransport.this.close();
+			});
+		}
+
+		/**
+		 * Closes the transport immediately.
+		 */
+		@Override
+		public void close() {
+			this.lock.lock();
+			try {
+				if (this.closed) {
+					logger.debug("Session transport {} already closed", this.sessionId);
+					return;
+				}
+
+				this.closed = true;
+
+				this.sseBuilder.complete();
+				logger.debug("Successfully completed SSE builder for session {}", sessionId);
+			}
+			catch (Exception e) {
+				logger.warn("Failed to complete SSE builder for session {}: {}", sessionId, e.getMessage());
+			}
+			finally {
+				this.lock.unlock();
+			}
+		}
+
+	}
+
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for creating instances of {@link WebMvcStreamableServerTransportProvider}.
+	 */
+	public static class Builder {
+
+		private ObjectMapper objectMapper;
+
+		private String mcpEndpoint = "/mcp";
+
+		private boolean disallowDelete = false;
+
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
+		/**
+		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * messages.
+		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public Builder objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint URI where clients should send their JSON-RPC messages.
+		 * @param mcpEndpoint The MCP endpoint URI. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if mcpEndpoint is null
+		 */
+		public Builder mcpEndpoint(String mcpEndpoint) {
+			Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
+			this.mcpEndpoint = mcpEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets whether to disallow DELETE requests on the endpoint.
+		 * @param disallowDelete true to disallow DELETE requests, false otherwise
+		 * @return this builder instance
+		 */
+		public Builder disallowDelete(boolean disallowDelete) {
+			this.disallowDelete = disallowDelete;
+			return this;
+		}
+
+		/**
+		 * Sets the context extractor that allows providing the MCP feature
+		 * implementations to inspect HTTP transport level metadata that was present at
+		 * HTTP request processing time. This allows to extract custom headers and other
+		 * useful data for use during execution later on in the process.
+		 * @param contextExtractor The contextExtractor to fill in a
+		 * {@link McpTransportContext}.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "contextExtractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
+		/**
+		 * Builds a new instance of {@link WebMvcStreamableServerTransportProvider} with
+		 * the configured settings.
+		 * @return A new WebMvcStreamableServerTransportProvider instance
+		 * @throws IllegalStateException if required parameters are not set
+		 */
+		public WebMvcStreamableServerTransportProvider build() {
+			Assert.notNull(this.objectMapper, "ObjectMapper must be set");
+			Assert.notNull(this.mcpEndpoint, "MCP endpoint must be set");
+
+			return new WebMvcStreamableServerTransportProvider(this.objectMapper, this.mcpEndpoint, this.disallowDelete,
+					this.contextExtractor);
+		}
+
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
new file mode 100644
index 000000000..66349216d
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
@@ -0,0 +1,121 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import org.apache.catalina.Context;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.Timeout;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
+import org.springframework.web.servlet.DispatcherServlet;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerResponse;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import reactor.netty.DisposableServer;
+
+/**
+ * Tests for {@link McpAsyncServer} using {@link WebFluxSseServerTransportProvider}.
+ *
+ * @author Christian Tzolov
+ */
+@Timeout(15) // Giving extra time beyond the client timeout
+class WebMcpStreamableAsyncServerTransportTests extends AbstractMcpAsyncServerTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String MCP_ENDPOINT = "/mcp";
+
+	private DisposableServer httpServer;
+
+	private AnnotationConfigWebApplicationContext appContext;
+
+	private Tomcat tomcat;
+
+	private McpStreamableServerTransportProvider transportProvider;
+
+	@Configuration
+	@EnableWebMvc
+	static class TestConfig {
+
+		@Bean
+		public WebMvcStreamableServerTransportProvider webMvcSseServerTransportProvider() {
+			return WebMvcStreamableServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.mcpEndpoint(MCP_ENDPOINT)
+				.build();
+		}
+
+		@Bean
+		public RouterFunction routerFunction(
+				WebMvcStreamableServerTransportProvider transportProvider) {
+			return transportProvider.getRouterFunction();
+		}
+
+	}
+
+	private McpStreamableServerTransportProvider createMcpTransportProvider() {
+		// Set up Tomcat first
+		tomcat = new Tomcat();
+		tomcat.setPort(PORT);
+
+		// Set Tomcat base directory to java.io.tmpdir to avoid permission issues
+		String baseDir = System.getProperty("java.io.tmpdir");
+		tomcat.setBaseDir(baseDir);
+
+		// Use the same directory for document base
+		Context context = tomcat.addContext("", baseDir);
+
+		// Create and configure Spring WebMvc context
+		appContext = new AnnotationConfigWebApplicationContext();
+		appContext.register(TestConfig.class);
+		appContext.setServletContext(context.getServletContext());
+		appContext.refresh();
+
+		// Get the transport from Spring context
+		transportProvider = appContext.getBean(McpStreamableServerTransportProvider.class);
+
+		// Create DispatcherServlet with our Spring context
+		DispatcherServlet dispatcherServlet = new DispatcherServlet(appContext);
+
+		// Add servlet to Tomcat and get the wrapper
+		var wrapper = Tomcat.addServlet(context, "dispatcherServlet", dispatcherServlet);
+		wrapper.setLoadOnStartup(1);
+		context.addServletMappingDecoded("/*", "dispatcherServlet");
+
+		try {
+			tomcat.start();
+			tomcat.getConnector(); // Create and start the connector
+		}
+		catch (LifecycleException e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		return transportProvider;
+	}
+
+	@Override
+	protected McpServer.AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(createMcpTransportProvider());
+	}
+
+	@Override
+	protected void onStart() {
+	}
+
+	@Override
+	protected void onClose() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
new file mode 100644
index 000000000..cab487f12
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
@@ -0,0 +1,121 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import org.apache.catalina.Context;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.Timeout;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
+import org.springframework.web.servlet.DispatcherServlet;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerResponse;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import reactor.netty.DisposableServer;
+
+/**
+ * Tests for {@link McpAsyncServer} using {@link WebFluxSseServerTransportProvider}.
+ *
+ * @author Christian Tzolov
+ */
+@Timeout(15) // Giving extra time beyond the client timeout
+class WebMcpStreamableSyncServerTransportTests extends AbstractMcpSyncServerTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String MCP_ENDPOINT = "/mcp";
+
+	private DisposableServer httpServer;
+
+	private AnnotationConfigWebApplicationContext appContext;
+
+	private Tomcat tomcat;
+
+	private McpStreamableServerTransportProvider transportProvider;
+
+	@Configuration
+	@EnableWebMvc
+	static class TestConfig {
+
+		@Bean
+		public WebMvcStreamableServerTransportProvider webMvcSseServerTransportProvider() {
+			return WebMvcStreamableServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.mcpEndpoint(MCP_ENDPOINT)
+				.build();
+		}
+
+		@Bean
+		public RouterFunction routerFunction(
+				WebMvcStreamableServerTransportProvider transportProvider) {
+			return transportProvider.getRouterFunction();
+		}
+
+	}
+
+	private McpStreamableServerTransportProvider createMcpTransportProvider() {
+		// Set up Tomcat first
+		tomcat = new Tomcat();
+		tomcat.setPort(PORT);
+
+		// Set Tomcat base directory to java.io.tmpdir to avoid permission issues
+		String baseDir = System.getProperty("java.io.tmpdir");
+		tomcat.setBaseDir(baseDir);
+
+		// Use the same directory for document base
+		Context context = tomcat.addContext("", baseDir);
+
+		// Create and configure Spring WebMvc context
+		appContext = new AnnotationConfigWebApplicationContext();
+		appContext.register(TestConfig.class);
+		appContext.setServletContext(context.getServletContext());
+		appContext.refresh();
+
+		// Get the transport from Spring context
+		transportProvider = appContext.getBean(McpStreamableServerTransportProvider.class);
+
+		// Create DispatcherServlet with our Spring context
+		DispatcherServlet dispatcherServlet = new DispatcherServlet(appContext);
+
+		// Add servlet to Tomcat and get the wrapper
+		var wrapper = Tomcat.addServlet(context, "dispatcherServlet", dispatcherServlet);
+		wrapper.setLoadOnStartup(1);
+		context.addServletMappingDecoded("/*", "dispatcherServlet");
+
+		try {
+			tomcat.start();
+			tomcat.getConnector(); // Create and start the connector
+		}
+		catch (LifecycleException e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		return transportProvider;
+	}
+
+	@Override
+	protected McpServer.SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(createMcpTransportProvider());
+	}
+
+	@Override
+	protected void onStart() {
+	}
+
+	@Override
+	protected void onClose() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index 9f2d6abff..45f6b94f0 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -4,67 +4,32 @@
 package io.modelcontextprotocol.server;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.awaitility.Awaitility.await;
-import static org.mockito.Mockito.mock;
 
 import java.time.Duration;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.TimeUnit;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.Function;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
-import org.springframework.web.client.RestClient;
+import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 import org.springframework.web.servlet.function.RouterFunction;
 import org.springframework.web.servlet.function.ServerResponse;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
+import io.modelcontextprotocol.AbstractMcpClientServerIntegrationTests;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
+import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.SingleSessionSyncSpecification;
 import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
-import io.modelcontextprotocol.spec.McpError;
-import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
-import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
-import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
-import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
-import io.modelcontextprotocol.spec.McpSchema.Role;
-import io.modelcontextprotocol.spec.McpSchema.Root;
-import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.Tool;
-import reactor.core.publisher.Mono;
 import reactor.core.scheduler.Schedulers;
-import reactor.test.StepVerifier;
 
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.web.client.RestClient;
-import org.springframework.web.servlet.config.annotation.EnableWebMvc;
-import org.springframework.web.servlet.function.RouterFunction;
-import org.springframework.web.servlet.function.ServerResponse;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.awaitility.Awaitility.await;
-import static org.mockito.Mockito.mock;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-
-import net.javacrumbs.jsonunit.core.Option;
-
-class WebMvcSseIntegrationTests {
+class WebMvcSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
 
@@ -72,7 +37,17 @@ class WebMvcSseIntegrationTests {
 
 	private WebMvcSseServerTransportProvider mcpServerTransportProvider;
 
-	McpClient.SyncSpec clientBuilder;
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
+
+		clientBuilders.put("httpclient",
+				McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + port).build())
+					.initializationTimeout(Duration.ofHours(10))
+					.requestTimeout(Duration.ofHours(10)));
+
+		clientBuilders.put("webflux", McpClient
+			.sync(WebFluxSseClientTransport.builder(WebClient.builder().baseUrl("http://localhost:" + port)).build()));
+	}
 
 	@Configuration
 	@EnableWebMvc
@@ -105,7 +80,7 @@ public void before() {
 			throw new RuntimeException("Failed to start Tomcat", e);
 		}
 
-		clientBuilder = McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT).build());
+		prepareClients(PORT, MESSAGE_ENDPOINT);
 
 		// Get the transport from Spring context
 		mcpServerTransportProvider = tomcatServer.appContext().getBean(WebMvcSseServerTransportProvider.class);
@@ -133,1102 +108,14 @@ public void after() {
 		}
 	}
 
-	// ---------------------------------------
-	// Sampling Tests
-	// ---------------------------------------
-	@Test
-	void testCreateMessageWithoutSamplingCapabilities() {
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
-				return Mono.just(mock(CallToolResult.class));
-			})
-			.build();
-
-		//@formatter:off
-		var server = McpServer.async(mcpServerTransportProvider)
-				.serverInfo("test-server", "1.0.0")
-				.tools(tool)
-				.build();
-		
-		try (
-			// Create client without sampling capabilities
-			var client = clientBuilder
-				.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
-				.build()) {//@formatter:on
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with sampling capabilities");
-			}
-		}
-		server.close();
-	}
-
-	@Test
-	void testCreateMessageSuccess() {
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		//@formatter:off		
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-				.serverInfo("test-server", "1.0.0")
-				.tools(tool)
-				.build();
-
-		try (
-			var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-				.capabilities(ClientCapabilities.builder().sampling().build())
-				.sampling(samplingHandler)
-				.build()) {//@formatter:on
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull().isEqualTo(callResponse);
-		}
-		mcpServer.close();
-	}
-
-	@Test
-	void testCreateMessageWithRequestTimeoutSuccess() throws InterruptedException {
-
-		// Client
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(4))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-
-		mcpClient.close();
-		mcpServer.close();
-	}
-
-	@Test
-	void testCreateMessageWithRequestTimeoutFail() throws InterruptedException {
-
-		// Client
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("Timeout");
-
-		mcpClient.close();
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Elicitation Tests
-	// ---------------------------------------
-	@Test
-	void testCreateElicitationWithoutElicitationCapabilities() {
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.createElicitation(mock(McpSchema.ElicitRequest.class)).block();
-
-				return Mono.just(mock(CallToolResult.class));
-			})
-			.build();
-
-		var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build();
-
-		try (
-				// Create client without elicitation capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with elicitation capabilities");
-			}
-		}
-		server.closeGracefully().block();
-	}
-
-	@Test
-	void testCreateElicitationSuccess() {
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-
-			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
-					Map.of("message", request.message()));
-		};
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = McpSchema.ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-		mcpServer.closeGracefully().block();
-	}
-
-	@Test
-	void testCreateElicitationWithRequestTimeoutSuccess() {
-
-		// Client
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
-					Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = McpSchema.ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(3))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	@Test
-	void testCreateElicitationWithRequestTimeoutFail() {
-
-		// Client
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
-					Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = McpSchema.ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("Timeout");
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	// ---------------------------------------
-	// Roots Tests
-	// ---------------------------------------
-	@Test
-	void testRootsSuccess() {
-		List roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-
-			// Remove a root
-			mcpClient.removeRoot(roots.get(0).uri());
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
-			});
-
-			// Add a new root
-			var root3 = new Root("uri3://", "root3");
-			mcpClient.addRoot(root3);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testRootsWithoutCapability() {
-
-		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.listRoots(); // try to list roots
-
-				return mock(CallToolResult.class);
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider).rootsChangeHandler((exchange, rootsUpdate) -> {
-		}).tools(tool).build();
-
-		try (
-				// Create client without roots capability
-				// No roots capability
-				var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().build()).build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			// Attempt to list roots should fail
-			try {
-				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
-			}
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testRootsNotificationWithEmptyRootsList() {
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(List.of()) // Empty roots list
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testRootsWithMultipleHandlers() {
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef1 = new AtomicReference<>();
-		AtomicReference> rootsRef2 = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef1.set(rootsUpdate))
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef2.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef1.get()).containsAll(roots);
-				assertThat(rootsRef2.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testRootsServerCloseWithActiveSubscription() {
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Tools Tests
-	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
-	@Test
-	void testToolCallSuccess() {
-
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull().isEqualTo(callResponse);
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testThrowingToolCallIsCaughtBeforeTimeout() {
-		McpSyncServer mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(new McpServerFeatures.SyncToolSpecification(
-					new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
-						// We trigger a timeout on blocking read, raising an exception
-						Mono.never().block(Duration.ofSeconds(1));
-						return null;
-					}))
-			.build();
-
-		try (var mcpClient = clientBuilder.requestTimeout(Duration.ofMillis(6666)).build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// We expect the tool call to fail immediately with the exception raised by
-			// the offending tool
-			// instead of getting back a timeout.
-			assertThatExceptionOfType(McpError.class)
-				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
-				.withMessageContaining("Timeout on blocking read");
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testToolListChangeHandlingSuccess() {
-
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
-			// perform a blocking call to a remote service
-			String response = RestClient.create()
-				.get()
-				.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-				.retrieve()
-				.body(String.class);
-			assertThat(response).isNotBlank();
-			rootsRef.set(toolsUpdate);
-		}).build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			mcpServer.notifyToolsListChanged();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
-			});
-
-			// Remove a tool
-			mcpServer.removeTool("tool1");
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-
-			// Add a new tool
-			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
-				.tool(new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema))
-				.callHandler((exchange, request) -> callResponse)
-				.build();
-
-			mcpServer.addTool(tool2);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testInitialize() {
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider).build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testPingSuccess() {
-		// Create server with a tool that uses ping functionality
-		AtomicReference executionOrder = new AtomicReference<>("");
-
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("ping-async-test", "Test ping async behavior", emptyJsonSchema),
-				(exchange, request) -> {
-
-					executionOrder.set(executionOrder.get() + "1");
-
-					// Test async ping behavior
-					return exchange.ping().doOnNext(result -> {
-
-						assertThat(result).isNotNull();
-						// Ping should return an empty object or map
-						assertThat(result).isInstanceOf(Map.class);
-
-						executionOrder.set(executionOrder.get() + "2");
-						assertThat(result).isNotNull();
-					}).then(Mono.fromCallable(() -> {
-						executionOrder.set(executionOrder.get() + "3");
-						return new CallToolResult("Async ping test completed", false);
-					}));
-				});
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call the tool that tests ping async behavior
-			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("ping-async-test", Map.of()));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Async ping test completed");
-
-			// Verify execution order
-			assertThat(executionOrder.get()).isEqualTo("123");
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Tool Structured Output Schema Tests
-	// ---------------------------------------
-
-	@Test
-	void testStructuredOutputValidationSuccess() {
-		// Create a tool with output schema
-		Map outputSchema = Map.of(
-				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
-						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
-				"required", List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					String expression = (String) request.getOrDefault("expression", "2 + 3");
-					double result = evaluateExpression(expression);
-					return CallToolResult.builder()
-						.structuredContent(
-								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Verify tool is listed with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call tool with valid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-
-			// In WebMVC, structured content is returned properly
-			if (response.structuredContent() != null) {
-				assertThat(response.structuredContent()).containsEntry("result", 5.0)
-					.containsEntry("operation", "2 + 3")
-					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
-			}
-			else {
-				// Fallback to checking content if structured content is not available
-				assertThat(response.content()).isNotEmpty();
-			}
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testStructuredOutputValidationFailure() {
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
-				List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return invalid structured output. Result should be number, missing
-					// operation
-					return CallToolResult.builder()
-						.addTextContent("Invalid calculation")
-						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool with invalid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).contains("Validation failed");
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testStructuredOutputMissingStructuredContent() {
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return result without structured content but tool has output schema
-					return CallToolResult.builder().addTextContent("Calculation completed").build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool that should return structured content but doesn't
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).isEqualTo(
-					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testStructuredOutputRuntimeToolAddition() {
-		// Start server without tools
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Initially no tools
-			assertThat(mcpClient.listTools().tools()).isEmpty();
-
-			// Add tool with output schema at runtime
-			Map outputSchema = Map.of("type", "object", "properties",
-					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
-					List.of("message", "count"));
-
-			Tool dynamicTool = Tool.builder()
-				.name("dynamic-tool")
-				.description("Dynamically added tool")
-				.outputSchema(outputSchema)
-				.build();
-
-			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
-					(exchange, request) -> {
-						int count = (Integer) request.getOrDefault("count", 1);
-						return CallToolResult.builder()
-							.addTextContent("Dynamic tool executed " + count + " times")
-							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
-							.build();
-					});
-
-			// Add tool to server
-			mcpServer.addTool(toolSpec);
-
-			// Wait for tool list change notification
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(mcpClient.listTools().tools()).hasSize(1);
-			});
-
-			// Verify tool was added with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call dynamically added tool
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
-				.isEqualTo("Dynamic tool executed 3 times");
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"count":3,"message":"Dynamic execution"}"""));
-		}
-
-		mcpServer.close();
+	@Override
+	protected AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(mcpServerTransportProvider);
 	}
 
-	private double evaluateExpression(String expression) {
-		// Simple expression evaluator for testing
-		return switch (expression) {
-			case "2 + 3" -> 5.0;
-			case "10 * 2" -> 20.0;
-			case "7 + 8" -> 15.0;
-			case "5 + 3" -> 8.0;
-			default -> 0.0;
-		};
+	@Override
+	protected SingleSessionSyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(mcpServerTransportProvider);
 	}
 
 }
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
new file mode 100644
index 000000000..f99b016ff
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -0,0 +1,165 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol.server;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.Duration;
+
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerResponse;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.AbstractMcpClientServerIntegrationTests;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.SyncSpecification;
+import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpSchema;
+import reactor.core.scheduler.Schedulers;
+
+class WebMvcStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String MESSAGE_ENDPOINT = "/mcp/message";
+
+	private WebMvcStreamableServerTransportProvider mcpServerTransportProvider;
+
+	@Configuration
+	@EnableWebMvc
+	static class TestConfig {
+
+		@Bean
+		public WebMvcStreamableServerTransportProvider webMvcStreamableServerTransportProvider() {
+			return WebMvcStreamableServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.mcpEndpoint(MESSAGE_ENDPOINT)
+				.build();
+		}
+
+		@Bean
+		public RouterFunction routerFunction(
+				WebMvcStreamableServerTransportProvider transportProvider) {
+			return transportProvider.getRouterFunction();
+		}
+
+	}
+
+	private TomcatTestUtil.TomcatServer tomcatServer;
+
+	@BeforeEach
+	public void before() {
+
+		tomcatServer = TomcatTestUtil.createTomcatServer("", PORT, TestConfig.class);
+
+		try {
+			tomcatServer.tomcat().start();
+			assertThat(tomcatServer.tomcat().getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+						.endpoint(MESSAGE_ENDPOINT)
+						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
+
+		clientBuilders.put("webflux",
+				McpClient.sync(WebClientStreamableHttpTransport
+					.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
+					.endpoint(MESSAGE_ENDPOINT)
+					.build()));
+
+		// Get the transport from Spring context
+		this.mcpServerTransportProvider = tomcatServer.appContext()
+			.getBean(WebMvcStreamableServerTransportProvider.class);
+
+	}
+
+	@Override
+	protected AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(this.mcpServerTransportProvider);
+	}
+
+	@Override
+	protected SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(this.mcpServerTransportProvider);
+	}
+
+	@AfterEach
+	public void after() {
+		reactor.netty.http.HttpResources.disposeLoopsAndConnections();
+		if (mcpServerTransportProvider != null) {
+			mcpServerTransportProvider.closeGracefully().block();
+		}
+		Schedulers.shutdownNow();
+		if (tomcatServer.appContext() != null) {
+			tomcatServer.appContext().close();
+		}
+		if (tomcatServer.tomcat() != null) {
+			try {
+				tomcatServer.tomcat().stop();
+				tomcatServer.tomcat().destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void simple(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var server = McpServer.async(mcpServerTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1000))
+			.build();
+
+		try (
+				// Create client without sampling capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+					.requestTimeout(Duration.ofSeconds(1000))
+					.build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+		}
+		server.closeGracefully();
+	}
+
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
+
+		clientBuilders.put("httpclient", McpClient
+			.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + port).endpoint(mcpEndpoint).build())
+			.initializationTimeout(Duration.ofHours(10))
+			.requestTimeout(Duration.ofHours(10)));
+
+		clientBuilders.put("webflux",
+				McpClient.sync(WebClientStreamableHttpTransport
+					.builder(WebClient.builder().baseUrl("http://localhost:" + port))
+					.endpoint(mcpEndpoint)
+					.build()));
+	}
+
+}
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index f24d9fab2..cc34e96d4 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -91,6 +91,13 @@
 			${logback.version}
 		
 
+		
+			net.javacrumbs.json-unit
+			json-unit-assertj
+			${json-unit-assertj.version}
+		
+
+
 	
 
 
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
new file mode 100644
index 000000000..d3d4fc071
--- /dev/null
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -0,0 +1,1274 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol;
+
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.awaitility.Awaitility.await;
+import static org.mockito.Mockito.mock;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Function;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpSyncServer;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
+import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
+import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
+import io.modelcontextprotocol.spec.McpSchema.Role;
+import io.modelcontextprotocol.spec.McpSchema.Root;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import net.javacrumbs.jsonunit.core.Option;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+public abstract class AbstractMcpClientServerIntegrationTests {
+
+	protected ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
+
+	abstract protected void prepareClients(int port, String mcpEndpoint);
+
+	abstract protected McpServer.AsyncSpecification prepareAsyncServerBuilder();
+
+	abstract protected McpServer.SyncSpecification prepareSyncServerBuilder();
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void simple(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1000))
+			.build();
+
+		try (
+				// Create client without sampling capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+					.requestTimeout(Duration.ofSeconds(1000))
+					.build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+		}
+		server.closeGracefully();
+	}
+
+	// ---------------------------------------
+	// Sampling Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageWithoutSamplingCapabilities(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+				exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
+				return Mono.just(mock(CallToolResult.class));
+			})
+			.build();
+
+		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
+
+		try (
+				// Create client without sampling capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+					.build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+			try {
+				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class)
+					.hasMessage("Client must be configured with sampling capabilities");
+			}
+		}
+		server.closeGracefully();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		//@formatter:off		
+		var mcpServer = prepareAsyncServerBuilder()
+				.serverInfo("test-server", "1.0.0")
+				.tools(tool)
+				.build();
+
+		try (
+			var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+				.capabilities(ClientCapabilities.builder().sampling().build())
+				.sampling(samplingHandler)
+				.build()) {//@formatter:on
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull().isEqualTo(callResponse);
+		}
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws InterruptedException {
+
+		// Client
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build();
+
+		// Server
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(4))
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response).isEqualTo(callResponse);
+
+		mcpClient.close();
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateMessageWithRequestTimeoutFail(String clientType) throws InterruptedException {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build();
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1))
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+		}).withMessageContaining("Timeout");
+
+		mcpClient.close();
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Elicitation Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				exchange.createElicitation(mock(McpSchema.ElicitRequest.class)).block();
+
+				return Mono.just(mock(CallToolResult.class));
+			})
+			.build();
+
+		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
+
+		try (
+				// Create client without elicitation capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+			try {
+				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class)
+					.hasMessage("Client must be configured with elicitation capabilities");
+			}
+		}
+		server.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+
+			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
+					Map.of("message", request.message()));
+		};
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = McpSchema.ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+		}
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
+					Map.of("message", request.message()));
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build();
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = McpSchema.ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(3))
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response).isEqualTo(callResponse);
+
+		mcpClient.closeGracefully();
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCreateElicitationWithRequestTimeoutFail(String clientType) {
+
+		var latch = new CountDownLatch(1);
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+
+			try {
+				if (!latch.await(2, TimeUnit.SECONDS)) {
+					throw new RuntimeException("Timeout waiting for elicitation processing");
+				}
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build();
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		AtomicReference resultRef = new AtomicReference<>();
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				return exchange.createElicitation(elicitationRequest)
+					.doOnNext(resultRef::set)
+					.then(Mono.just(callResponse));
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1)) // 1 second.
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+		}).withMessageContaining("within 1000ms");
+
+		ElicitResult elicitResult = resultRef.get();
+		assertThat(elicitResult).isNull();
+
+		mcpClient.closeGracefully();
+		mcpServer.closeGracefully().block();
+	}
+
+	// ---------------------------------------
+	// Roots Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(rootsRef.get()).isNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(roots);
+			});
+
+			// Remove a root
+			mcpClient.removeRoot(roots.get(0).uri());
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
+			});
+
+			// Add a new root
+			var root3 = new Root("uri3://", "root3");
+			mcpClient.addRoot(root3);
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsWithoutCapability(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				exchange.listRoots(); // try to list roots
+
+				return mock(CallToolResult.class);
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().rootsChangeHandler((exchange, rootsUpdate) -> {
+		}).tools(tool).build();
+
+		try (
+				// Create client without roots capability
+				// No roots capability
+				var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().build()).build()) {
+
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			// Attempt to list roots should fail
+			try {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
+			}
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsNotificationWithEmptyRootsList(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(List.of()) // Empty roots list
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).isEmpty();
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsWithMultipleHandlers(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"));
+
+		AtomicReference> rootsRef1 = new AtomicReference<>();
+		AtomicReference> rootsRef2 = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef1.set(rootsUpdate))
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef2.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef1.get()).containsAll(roots);
+				assertThat(rootsRef2.get()).containsAll(roots);
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testRootsServerCloseWithActiveSubscription(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"));
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(roots);
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tools Tests
+	// ---------------------------------------
+
+	String emptyJsonSchema = """
+			{
+				"$schema": "http://json-schema.org/draft-07/schema#",
+				"type": "object",
+				"properties": {}
+			}
+			""";
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolCallSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				try {
+					HttpResponse response = HttpClient.newHttpClient()
+						.send(HttpRequest.newBuilder()
+							.uri(URI.create(
+									"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+							.GET()
+							.build(), HttpResponse.BodyHandlers.ofString());
+					String responseBody = response.body();
+					assertThat(responseBody).isNotBlank();
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+
+				return callResponse;
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull().isEqualTo(callResponse);
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpSyncServer mcpServer = prepareSyncServerBuilder()
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(McpServerFeatures.SyncToolSpecification.builder()
+				.tool(Tool.builder()
+					.name("tool1")
+					.description("tool1 description")
+					.inputSchema(emptyJsonSchema)
+					.build())
+				.callHandler((exchange, request) -> {
+					// We trigger a timeout on blocking read, raising an exception
+					Mono.never().block(Duration.ofSeconds(1));
+					return null;
+				})
+				.build())
+			.build();
+
+		try (var mcpClient = clientBuilder.requestTimeout(Duration.ofMillis(6666)).build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// We expect the tool call to fail immediately with the exception raised by
+			// the offending tool
+			// instead of getting back a timeout.
+			assertThatExceptionOfType(McpError.class)
+				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
+				.withMessageContaining("Timeout on blocking read");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolListChangeHandlingSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+				// perform a blocking call to a remote service
+				try {
+					HttpResponse response = HttpClient.newHttpClient()
+						.send(HttpRequest.newBuilder()
+							.uri(URI.create(
+									"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+							.GET()
+							.build(), HttpResponse.BodyHandlers.ofString());
+					String responseBody = response.body();
+					assertThat(responseBody).isNotBlank();
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+				return callResponse;
+			})
+			.build();
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
+			// perform a blocking call to a remote service
+			try {
+				HttpResponse response = HttpClient.newHttpClient()
+					.send(HttpRequest.newBuilder()
+						.uri(URI.create(
+								"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+						.GET()
+						.build(), HttpResponse.BodyHandlers.ofString());
+				String responseBody = response.body();
+				assertThat(responseBody).isNotBlank();
+			}
+			catch (Exception e) {
+				e.printStackTrace();
+			}
+
+			rootsRef.set(toolsUpdate);
+		}).build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(rootsRef.get()).isNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			mcpServer.notifyToolsListChanged();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
+			});
+
+			// Remove a tool
+			mcpServer.removeTool("tool1");
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).isEmpty();
+			});
+
+			// Add a new tool
+			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
+				.tool(Tool.builder()
+					.name("tool2")
+					.description("tool2 description")
+					.inputSchema(emptyJsonSchema)
+					.build())
+				.callHandler((exchange, request) -> callResponse)
+				.build();
+
+			mcpServer.addTool(tool2);
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testInitialize(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var mcpServer = prepareSyncServerBuilder().build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testPingSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that uses ping functionality
+		AtomicReference executionOrder = new AtomicReference<>("");
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder()
+				.name("ping-async-test")
+				.description("Test ping async behavior")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				executionOrder.set(executionOrder.get() + "1");
+
+				// Test async ping behavior
+				return exchange.ping().doOnNext(result -> {
+
+					assertThat(result).isNotNull();
+					// Ping should return an empty object or map
+					assertThat(result).isInstanceOf(Map.class);
+
+					executionOrder.set(executionOrder.get() + "2");
+					assertThat(result).isNotNull();
+				}).then(Mono.fromCallable(() -> {
+					executionOrder.set(executionOrder.get() + "3");
+					return new CallToolResult("Async ping test completed", false);
+				}));
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that tests ping async behavior
+			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("ping-async-test", Map.of()));
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Async ping test completed");
+
+			// Verify execution order
+			assertThat(executionOrder.get()).isEqualTo("123");
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				String expression = (String) request.arguments().getOrDefault("expression", "2 + 3");
+				double result = evaluateExpression(expression);
+				return CallToolResult.builder()
+					.structuredContent(
+							Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			// In WebMVC, structured content is returned properly
+			if (response.structuredContent() != null) {
+				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+					.containsEntry("operation", "2 + 3")
+					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
+			}
+			else {
+				// Fallback to checking content if structured content is not available
+				assertThat(response.content()).isNotEmpty();
+			}
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationFailure(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				// Return invalid structured output. Result should be number, missing
+				// operation
+				return CallToolResult.builder()
+					.addTextContent("Invalid calculation")
+					.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputMissingStructuredContent(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				// Return result without structured content but tool has output schema
+				return CallToolResult.builder().addTextContent("Calculation completed").build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputRuntimeToolAddition(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Start server without tools
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpServerFeatures.SyncToolSpecification toolSpec = McpServerFeatures.SyncToolSpecification.builder()
+				.tool(dynamicTool)
+				.callHandler((exchange, request) -> {
+					int count = (Integer) request.arguments().getOrDefault("count", 1);
+					return CallToolResult.builder()
+						.addTextContent("Dynamic tool executed " + count + " times")
+						.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+						.build();
+				})
+				.build();
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index fcd42a433..1b3eee3c8 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -296,7 +296,7 @@ private McpNotificationHandler asyncRootsListChangedNotificationHandler(
 			List, Mono>> rootsChangeConsumers) {
 		return (exchange, params) -> exchange.listRoots()
 			.flatMap(listRootsResult -> Flux.fromIterable(rootsChangeConsumers)
-				.flatMap(consumer -> consumer.apply(exchange, listRootsResult.roots()))
+				.flatMap(consumer -> Mono.defer(() -> consumer.apply(exchange, listRootsResult.roots())))
 				.onErrorResume(error -> {
 					logger.error("Error handling roots list change notification", error);
 					return Mono.empty();
@@ -506,7 +506,7 @@ private McpRequestHandler toolsCallRequestHandler() {
 				return Mono.error(new McpError("Tool not found: " + callToolRequest.name()));
 			}
 
-			return toolSpecification.map(tool -> tool.callHandler().apply(exchange, callToolRequest))
+			return toolSpecification.map(tool -> Mono.defer(() -> tool.callHandler().apply(exchange, callToolRequest)))
 				.orElse(Mono.error(new McpError("Tool not found: " + callToolRequest.name())));
 		};
 	}
@@ -634,7 +634,7 @@ private McpRequestHandler resourcesReadRequestHand
 				.findFirst()
 				.orElseThrow(() -> new McpError("Resource not found: " + resourceUri));
 
-			return specification.readHandler().apply(exchange, resourceRequest);
+			return Mono.defer(() -> specification.readHandler().apply(exchange, resourceRequest));
 		};
 	}
 
@@ -740,7 +740,7 @@ private McpRequestHandler promptsGetRequestHandler()
 				return Mono.error(new McpError("Prompt not found: " + promptRequest.name()));
 			}
 
-			return specification.promptHandler().apply(exchange, promptRequest);
+			return Mono.defer(() -> specification.promptHandler().apply(exchange, promptRequest));
 		};
 	}
 
@@ -845,7 +845,7 @@ private McpRequestHandler completionCompleteRequestHan
 				return Mono.error(new McpError("AsyncCompletionSpecification not found: " + request.ref()));
 			}
 
-			return specification.completionHandler().apply(exchange, request);
+			return Mono.defer(() -> specification.completionHandler().apply(exchange, request));
 		};
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index 7a1e90770..0ba8bf929 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -4,9 +4,17 @@
 
 package io.modelcontextprotocol.server;
 
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
 import java.time.Duration;
 import java.util.List;
 
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
@@ -18,18 +26,9 @@
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
 /**
  * Test suite for the {@link McpAsyncServer} that can be used with different
  * {@link io.modelcontextprotocol.spec.McpServerTransportProvider} implementations.
@@ -65,10 +64,7 @@ void tearDown() {
 	// ---------------------------------------
 	// Server Lifecycle Tests
 	// ---------------------------------------
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "sse", "streamable" })
-	void testConstructorWithInvalidArguments(String serverType) {
+	void testConstructorWithInvalidArguments() {
 		assertThatThrownBy(() -> McpServer.async((McpServerTransportProvider) null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Transport provider must not be null");

From bde1b6beec5be35c1ce936ae18691397d8e0dd38 Mon Sep 17 00:00:00 2001
From: Zachary German <37987384+ZachGerman@users.noreply.github.com>
Date: Wed, 30 Jul 2025 08:58:28 -0700
Subject: [PATCH 021/125] feat: HttpServlet Streamable HTTP server
 implementation (#290)

Implementation of the Streamable HTTP transport provider for the Servlet API.

---
Signed-off-by: Christian Tzolov 
Co-authored-by: Christian Tzolov 
Co-authored-by: Zachary German 
---
 ...FluxStreamableServerTransportProvider.java |    2 +-
 ...vletStreamableServerTransportProvider.java |  803 +++++++++++
 ...stractMcpClientServerIntegrationTests.java | 1271 +++++++++++++++++
 ...HttpServletStreamableAsyncServerTests.java |   35 +
 ...HttpServletStreamableIntegrationTests.java |   89 ++
 .../HttpServletStreamableSyncServerTests.java |   35 +
 6 files changed, 2234 insertions(+), 1 deletion(-)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index 750828adb..e277e4749 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -440,4 +440,4 @@ public WebFluxStreamableServerTransportProvider build() {
 
 	}
 
-}
+}
\ No newline at end of file
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
new file mode 100644
index 000000000..4d2dc62f4
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
@@ -0,0 +1,803 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server.transport;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.locks.ReentrantLock;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.spec.HttpHeaders;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpStreamableServerSession;
+import io.modelcontextprotocol.spec.McpStreamableServerTransport;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import io.modelcontextprotocol.util.Assert;
+import jakarta.servlet.AsyncContext;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.annotation.WebServlet;
+import jakarta.servlet.http.HttpServlet;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import reactor.core.publisher.Mono;
+
+/**
+ * Server-side implementation of the Model Context Protocol (MCP) streamable transport
+ * layer using HTTP with Server-Sent Events (SSE) through HttpServlet. This implementation
+ * provides a bridge between synchronous HttpServlet operations and reactive programming
+ * patterns to maintain compatibility with the reactive transport interface.
+ *
+ * 

+ * This is the HttpServlet equivalent of
+ * {@link io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider}
+ * for the core MCP module, providing streamable HTTP transport functionality without
+ * Spring dependencies.
+ *
+ * @author Zachary German
+ * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
+ * @see McpStreamableServerTransportProvider
+ * @see HttpServlet
+ */
+@WebServlet(asyncSupported = true)
+public class HttpServletStreamableServerTransportProvider extends HttpServlet
+		implements McpStreamableServerTransportProvider {
+
+	private static final Logger logger = LoggerFactory.getLogger(HttpServletStreamableServerTransportProvider.class);
+
+	/**
+	 * Event type for JSON-RPC messages sent through the SSE connection.
+	 */
+	public static final String MESSAGE_EVENT_TYPE = "message";
+
+	/**
+	 * Event type for sending the message endpoint URI to clients.
+	 */
+	public static final String ENDPOINT_EVENT_TYPE = "endpoint";
+
+	/**
+	 * Header name for the response media types accepted by the requester.
+	 */
+	private static final String ACCEPT = "Accept";
+
+	public static final String UTF_8 = "UTF-8";
+
+	public static final String APPLICATION_JSON = "application/json";
+
+	public static final String TEXT_EVENT_STREAM = "text/event-stream";
+
+	public static final String FAILED_TO_SEND_ERROR_RESPONSE = "Failed to send error response: {}";
+
+	/**
+	 * The endpoint URI where clients should send their JSON-RPC messages. Defaults to
+	 * "/mcp".
+	 */
+	private final String mcpEndpoint;
+
+	/**
+	 * Flag indicating whether DELETE requests are disallowed on the endpoint.
+	 */
+	private final boolean disallowDelete;
+
+	private final ObjectMapper objectMapper;
+
+	private McpStreamableServerSession.Factory sessionFactory;
+
+	/**
+	 * Map of active client sessions, keyed by mcp-session-id.
+	 */
+	private final ConcurrentHashMap sessions = new ConcurrentHashMap<>();
+
+	private McpTransportContextExtractor contextExtractor;
+
+	/**
+	 * Flag indicating if the transport is shutting down.
+	 */
+	private volatile boolean isClosing = false;
+
+	/**
+	 * Constructs a new HttpServletStreamableServerTransportProvider instance.
+	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * of messages.
+	 * @param mcpEndpoint The endpoint URI where clients should send their JSON-RPC
+	 * messages via HTTP. This endpoint will handle GET, POST, and DELETE requests.
+	 * @param disallowDelete Whether to disallow DELETE requests on the endpoint.
+	 * @param contextExtractor The extractor for transport context from the request.
+	 * @throws IllegalArgumentException if any parameter is null
+	 */
+	private HttpServletStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
+			boolean disallowDelete, McpTransportContextExtractor contextExtractor) {
+		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
+		Assert.notNull(contextExtractor, "Context extractor must not be null");
+
+		this.objectMapper = objectMapper;
+		this.mcpEndpoint = mcpEndpoint;
+		this.disallowDelete = disallowDelete;
+		this.contextExtractor = contextExtractor;
+	}
+
+	@Override
+	public void setSessionFactory(McpStreamableServerSession.Factory sessionFactory) {
+		this.sessionFactory = sessionFactory;
+	}
+
+	/**
+	 * Broadcasts a notification to all connected clients through their SSE connections.
+	 * If any errors occur during sending to a particular client, they are logged but
+	 * don't prevent sending to other clients.
+	 * @param method The method name for the notification
+	 * @param params The parameters for the notification
+	 * @return A Mono that completes when the broadcast attempt is finished
+	 */
+	@Override
+	public Mono notifyClients(String method, Object params) {
+		if (this.sessions.isEmpty()) {
+			logger.debug("No active sessions to broadcast message to");
+			return Mono.empty();
+		}
+
+		logger.debug("Attempting to broadcast message to {} active sessions", this.sessions.size());
+
+		return Mono.fromRunnable(() -> {
+			this.sessions.values().parallelStream().forEach(session -> {
+				try {
+					session.sendNotification(method, params).block();
+				}
+				catch (Exception e) {
+					logger.error("Failed to send message to session {}: {}", session.getId(), e.getMessage());
+				}
+			});
+		});
+	}
+
+	/**
+	 * Initiates a graceful shutdown of the transport.
+	 * @return A Mono that completes when all cleanup operations are finished
+	 */
+	@Override
+	public Mono closeGracefully() {
+		return Mono.fromRunnable(() -> {
+			this.isClosing = true;
+			logger.debug("Initiating graceful shutdown with {} active sessions", this.sessions.size());
+
+			this.sessions.values().parallelStream().forEach(session -> {
+				try {
+					session.closeGracefully().block();
+				}
+				catch (Exception e) {
+					logger.error("Failed to close session {}: {}", session.getId(), e.getMessage());
+				}
+			});
+
+			this.sessions.clear();
+			logger.debug("Graceful shutdown completed");
+		});
+	}
+
+	/**
+	 * Handles GET requests to establish SSE connections and message replay.
+	 * @param request The HTTP servlet request
+	 * @param response The HTTP servlet response
+	 * @throws ServletException If a servlet-specific error occurs
+	 * @throws IOException If an I/O error occurs
+	 */
+	@Override
+	protected void doGet(HttpServletRequest request, HttpServletResponse response)
+			throws ServletException, IOException {
+
+		String requestURI = request.getRequestURI();
+		if (!requestURI.endsWith(mcpEndpoint)) {
+			response.sendError(HttpServletResponse.SC_NOT_FOUND);
+			return;
+		}
+
+		if (this.isClosing) {
+			response.sendError(HttpServletResponse.SC_SERVICE_UNAVAILABLE, "Server is shutting down");
+			return;
+		}
+
+		List badRequestErrors = new ArrayList<>();
+
+		String accept = request.getHeader(ACCEPT);
+		if (accept == null || !accept.contains(TEXT_EVENT_STREAM)) {
+			badRequestErrors.add("text/event-stream required in Accept header");
+		}
+
+		String sessionId = request.getHeader(HttpHeaders.MCP_SESSION_ID);
+
+		if (sessionId == null || sessionId.isBlank()) {
+			badRequestErrors.add("Session ID required in mcp-session-id header");
+		}
+
+		if (!badRequestErrors.isEmpty()) {
+			String combinedMessage = String.join("; ", badRequestErrors);
+			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST, new McpError(combinedMessage));
+			return;
+		}
+
+		McpStreamableServerSession session = this.sessions.get(sessionId);
+
+		if (session == null) {
+			response.sendError(HttpServletResponse.SC_NOT_FOUND);
+			return;
+		}
+
+		logger.debug("Handling GET request for session: {}", sessionId);
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		try {
+			response.setContentType(TEXT_EVENT_STREAM);
+			response.setCharacterEncoding(UTF_8);
+			response.setHeader("Cache-Control", "no-cache");
+			response.setHeader("Connection", "keep-alive");
+			response.setHeader("Access-Control-Allow-Origin", "*");
+
+			AsyncContext asyncContext = request.startAsync();
+			asyncContext.setTimeout(0);
+
+			HttpServletStreamableMcpSessionTransport sessionTransport = new HttpServletStreamableMcpSessionTransport(
+					sessionId, asyncContext, response.getWriter());
+
+			// Check if this is a replay request
+			if (request.getHeader(HttpHeaders.LAST_EVENT_ID) != null) {
+				String lastId = request.getHeader(HttpHeaders.LAST_EVENT_ID);
+
+				try {
+					session.replay(lastId)
+						.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+						.toIterable()
+						.forEach(message -> {
+							try {
+								sessionTransport.sendMessage(message)
+									.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+									.block();
+							}
+							catch (Exception e) {
+								logger.error("Failed to replay message: {}", e.getMessage());
+								asyncContext.complete();
+							}
+						});
+				}
+				catch (Exception e) {
+					logger.error("Failed to replay messages: {}", e.getMessage());
+					asyncContext.complete();
+				}
+			}
+			else {
+				// Establish new listening stream
+				McpStreamableServerSession.McpStreamableServerSessionStream listeningStream = session
+					.listeningStream(sessionTransport);
+
+				asyncContext.addListener(new jakarta.servlet.AsyncListener() {
+					@Override
+					public void onComplete(jakarta.servlet.AsyncEvent event) throws IOException {
+						logger.debug("SSE connection completed for session: {}", sessionId);
+						listeningStream.close();
+					}
+
+					@Override
+					public void onTimeout(jakarta.servlet.AsyncEvent event) throws IOException {
+						logger.debug("SSE connection timed out for session: {}", sessionId);
+						listeningStream.close();
+					}
+
+					@Override
+					public void onError(jakarta.servlet.AsyncEvent event) throws IOException {
+						logger.debug("SSE connection error for session: {}", sessionId);
+						listeningStream.close();
+					}
+
+					@Override
+					public void onStartAsync(jakarta.servlet.AsyncEvent event) throws IOException {
+						// No action needed
+					}
+				});
+			}
+		}
+		catch (Exception e) {
+			logger.error("Failed to handle GET request for session {}: {}", sessionId, e.getMessage());
+			response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
+		}
+	}
+
+	/**
+	 * Handles POST requests for incoming JSON-RPC messages from clients.
+	 * @param request The HTTP servlet request containing the JSON-RPC message
+	 * @param response The HTTP servlet response
+	 * @throws ServletException If a servlet-specific error occurs
+	 * @throws IOException If an I/O error occurs
+	 */
+	@Override
+	protected void doPost(HttpServletRequest request, HttpServletResponse response)
+			throws ServletException, IOException {
+
+		String requestURI = request.getRequestURI();
+		if (!requestURI.endsWith(mcpEndpoint)) {
+			response.sendError(HttpServletResponse.SC_NOT_FOUND);
+			return;
+		}
+
+		if (this.isClosing) {
+			response.sendError(HttpServletResponse.SC_SERVICE_UNAVAILABLE, "Server is shutting down");
+			return;
+		}
+
+		List badRequestErrors = new ArrayList<>();
+
+		String accept = request.getHeader(ACCEPT);
+		if (accept == null || !accept.contains(TEXT_EVENT_STREAM)) {
+			badRequestErrors.add("text/event-stream required in Accept header");
+		}
+		if (accept == null || !accept.contains(APPLICATION_JSON)) {
+			badRequestErrors.add("application/json required in Accept header");
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		try {
+			BufferedReader reader = request.getReader();
+			StringBuilder body = new StringBuilder();
+			String line;
+			while ((line = reader.readLine()) != null) {
+				body.append(line);
+			}
+
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body.toString());
+
+			// Handle initialization request
+			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest
+					&& jsonrpcRequest.method().equals(McpSchema.METHOD_INITIALIZE)) {
+				if (!badRequestErrors.isEmpty()) {
+					String combinedMessage = String.join("; ", badRequestErrors);
+					this.responseError(response, HttpServletResponse.SC_BAD_REQUEST, new McpError(combinedMessage));
+					return;
+				}
+
+				McpSchema.InitializeRequest initializeRequest = objectMapper.convertValue(jsonrpcRequest.params(),
+						new TypeReference() {
+						});
+				McpStreamableServerSession.McpStreamableServerSessionInit init = this.sessionFactory
+					.startSession(initializeRequest);
+				this.sessions.put(init.session().getId(), init.session());
+
+				try {
+					McpSchema.InitializeResult initResult = init.initResult().block();
+
+					response.setContentType(APPLICATION_JSON);
+					response.setCharacterEncoding(UTF_8);
+					response.setHeader(HttpHeaders.MCP_SESSION_ID, init.session().getId());
+					response.setStatus(HttpServletResponse.SC_OK);
+
+					String jsonResponse = objectMapper.writeValueAsString(new McpSchema.JSONRPCResponse(
+							McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), initResult, null));
+
+					PrintWriter writer = response.getWriter();
+					writer.write(jsonResponse);
+					writer.flush();
+					return;
+				}
+				catch (Exception e) {
+					logger.error("Failed to initialize session: {}", e.getMessage());
+					this.responseError(response, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
+							new McpError("Failed to initialize session: " + e.getMessage()));
+					return;
+				}
+			}
+
+			String sessionId = request.getHeader(HttpHeaders.MCP_SESSION_ID);
+
+			if (sessionId == null || sessionId.isBlank()) {
+				badRequestErrors.add("Session ID required in mcp-session-id header");
+			}
+
+			if (!badRequestErrors.isEmpty()) {
+				String combinedMessage = String.join("; ", badRequestErrors);
+				this.responseError(response, HttpServletResponse.SC_BAD_REQUEST, new McpError(combinedMessage));
+				return;
+			}
+
+			McpStreamableServerSession session = this.sessions.get(sessionId);
+
+			if (session == null) {
+				this.responseError(response, HttpServletResponse.SC_NOT_FOUND,
+						new McpError("Session not found: " + sessionId));
+				return;
+			}
+
+			if (message instanceof McpSchema.JSONRPCResponse jsonrpcResponse) {
+				session.accept(jsonrpcResponse)
+					.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+					.block();
+				response.setStatus(HttpServletResponse.SC_ACCEPTED);
+			}
+			else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
+				session.accept(jsonrpcNotification)
+					.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+					.block();
+				response.setStatus(HttpServletResponse.SC_ACCEPTED);
+			}
+			else if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
+				// For streaming responses, we need to return SSE
+				response.setContentType(TEXT_EVENT_STREAM);
+				response.setCharacterEncoding(UTF_8);
+				response.setHeader("Cache-Control", "no-cache");
+				response.setHeader("Connection", "keep-alive");
+				response.setHeader("Access-Control-Allow-Origin", "*");
+
+				AsyncContext asyncContext = request.startAsync();
+				asyncContext.setTimeout(0);
+
+				HttpServletStreamableMcpSessionTransport sessionTransport = new HttpServletStreamableMcpSessionTransport(
+						sessionId, asyncContext, response.getWriter());
+
+				try {
+					session.responseStream(jsonrpcRequest, sessionTransport)
+						.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+						.block();
+				}
+				catch (Exception e) {
+					logger.error("Failed to handle request stream: {}", e.getMessage());
+					asyncContext.complete();
+				}
+			}
+			else {
+				this.responseError(response, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
+						new McpError("Unknown message type"));
+			}
+		}
+		catch (IllegalArgumentException | IOException e) {
+			logger.error("Failed to deserialize message: {}", e.getMessage());
+			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
+					new McpError("Invalid message format: " + e.getMessage()));
+		}
+		catch (Exception e) {
+			logger.error("Error handling message: {}", e.getMessage());
+			try {
+				this.responseError(response, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
+						new McpError("Error processing message: " + e.getMessage()));
+			}
+			catch (IOException ex) {
+				logger.error(FAILED_TO_SEND_ERROR_RESPONSE, ex.getMessage());
+				response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, "Error processing message");
+			}
+		}
+	}
+
+	/**
+	 * Handles DELETE requests for session deletion.
+	 * @param request The HTTP servlet request
+	 * @param response The HTTP servlet response
+	 * @throws ServletException If a servlet-specific error occurs
+	 * @throws IOException If an I/O error occurs
+	 */
+	@Override
+	protected void doDelete(HttpServletRequest request, HttpServletResponse response)
+			throws ServletException, IOException {
+
+		String requestURI = request.getRequestURI();
+		if (!requestURI.endsWith(mcpEndpoint)) {
+			response.sendError(HttpServletResponse.SC_NOT_FOUND);
+			return;
+		}
+
+		if (this.isClosing) {
+			response.sendError(HttpServletResponse.SC_SERVICE_UNAVAILABLE, "Server is shutting down");
+			return;
+		}
+
+		if (this.disallowDelete) {
+			response.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED);
+			return;
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		if (request.getHeader(HttpHeaders.MCP_SESSION_ID) == null) {
+			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
+					new McpError("Session ID required in mcp-session-id header"));
+			return;
+		}
+
+		String sessionId = request.getHeader(HttpHeaders.MCP_SESSION_ID);
+		McpStreamableServerSession session = this.sessions.get(sessionId);
+
+		if (session == null) {
+			response.sendError(HttpServletResponse.SC_NOT_FOUND);
+			return;
+		}
+
+		try {
+			session.delete().contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)).block();
+			this.sessions.remove(sessionId);
+			response.setStatus(HttpServletResponse.SC_OK);
+		}
+		catch (Exception e) {
+			logger.error("Failed to delete session {}: {}", sessionId, e.getMessage());
+			try {
+				this.responseError(response, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
+						new McpError(e.getMessage()));
+			}
+			catch (IOException ex) {
+				logger.error(FAILED_TO_SEND_ERROR_RESPONSE, ex.getMessage());
+				response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, "Error deleting session");
+			}
+		}
+	}
+
+	public void responseError(HttpServletResponse response, int httpCode, McpError mcpError) throws IOException {
+		response.setContentType(APPLICATION_JSON);
+		response.setCharacterEncoding(UTF_8);
+		response.setStatus(httpCode);
+		String jsonError = objectMapper.writeValueAsString(mcpError);
+		PrintWriter writer = response.getWriter();
+		writer.write(jsonError);
+		writer.flush();
+		return;
+	}
+
+	/**
+	 * Sends an SSE event to a client with a specific ID.
+	 * @param writer The writer to send the event through
+	 * @param eventType The type of event (message or endpoint)
+	 * @param data The event data
+	 * @param id The event ID
+	 * @throws IOException If an error occurs while writing the event
+	 */
+	private void sendEvent(PrintWriter writer, String eventType, String data, String id) throws IOException {
+		if (id != null) {
+			writer.write("id: " + id + "\n");
+		}
+		writer.write("event: " + eventType + "\n");
+		writer.write("data: " + data + "\n\n");
+		writer.flush();
+
+		if (writer.checkError()) {
+			throw new IOException("Client disconnected");
+		}
+	}
+
+	/**
+	 * Cleans up resources when the servlet is being destroyed.
+	 * 

+	 * This method ensures a graceful shutdown by closing all client connections before
+	 * calling the parent's destroy method.
+	 */
+	@Override
+	public void destroy() {
+		closeGracefully().block();
+		super.destroy();
+	}
+
+	/**
+	 * Implementation of McpStreamableServerTransport for HttpServlet SSE sessions. This
+	 * class handles the transport-level communication for a specific client session.
+	 *
+	 * 

+	 * This class is thread-safe and uses a ReentrantLock to synchronize access to the
+	 * underlying PrintWriter to prevent race conditions when multiple threads attempt to
+	 * send messages concurrently.
+	 */
+
+	private class HttpServletStreamableMcpSessionTransport implements McpStreamableServerTransport {
+
+		private final String sessionId;
+
+		private final AsyncContext asyncContext;
+
+		private final PrintWriter writer;
+
+		private volatile boolean closed = false;
+
+		private final ReentrantLock lock = new ReentrantLock();
+
+		/**
+		 * Creates a new session transport with the specified ID and SSE writer.
+		 * @param sessionId The unique identifier for this session
+		 * @param asyncContext The async context for the session
+		 * @param writer The writer for sending server events to the client
+		 */
+		HttpServletStreamableMcpSessionTransport(String sessionId, AsyncContext asyncContext, PrintWriter writer) {
+			this.sessionId = sessionId;
+			this.asyncContext = asyncContext;
+			this.writer = writer;
+			logger.debug("Streamable session transport {} initialized with SSE writer", sessionId);
+		}
+
+		/**
+		 * Sends a JSON-RPC message to the client through the SSE connection.
+		 * @param message The JSON-RPC message to send
+		 * @return A Mono that completes when the message has been sent
+		 */
+		@Override
+		public Mono sendMessage(McpSchema.JSONRPCMessage message) {
+			return sendMessage(message, null);
+		}
+
+		/**
+		 * Sends a JSON-RPC message to the client through the SSE connection with a
+		 * specific message ID.
+		 * @param message The JSON-RPC message to send
+		 * @param messageId The message ID for SSE event identification
+		 * @return A Mono that completes when the message has been sent
+		 */
+		@Override
+		public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId) {
+			return Mono.fromRunnable(() -> {
+				if (this.closed) {
+					logger.debug("Attempted to send message to closed session: {}", this.sessionId);
+					return;
+				}
+
+				lock.lock();
+				try {
+					if (this.closed) {
+						logger.debug("Session {} was closed during message send attempt", this.sessionId);
+						return;
+					}
+
+					String jsonText = objectMapper.writeValueAsString(message);
+					HttpServletStreamableServerTransportProvider.this.sendEvent(writer, MESSAGE_EVENT_TYPE, jsonText,
+							messageId != null ? messageId : this.sessionId);
+					logger.debug("Message sent to session {} with ID {}", this.sessionId, messageId);
+				}
+				catch (Exception e) {
+					logger.error("Failed to send message to session {}: {}", this.sessionId, e.getMessage());
+					HttpServletStreamableServerTransportProvider.this.sessions.remove(this.sessionId);
+					this.asyncContext.complete();
+				}
+				finally {
+					lock.unlock();
+				}
+			});
+		}
+
+		/**
+		 * Converts data from one type to another using the configured ObjectMapper.
+		 * @param data The source data object to convert
+		 * @param typeRef The target type reference
+		 * @return The converted object of type T
+		 * @param  The target type
+		 */
+		@Override
+		public  T unmarshalFrom(Object data, TypeReference typeRef) {
+			return objectMapper.convertValue(data, typeRef);
+		}
+
+		/**
+		 * Initiates a graceful shutdown of the transport.
+		 * @return A Mono that completes when the shutdown is complete
+		 */
+		@Override
+		public Mono closeGracefully() {
+			return Mono.fromRunnable(() -> {
+				HttpServletStreamableMcpSessionTransport.this.close();
+			});
+		}
+
+		/**
+		 * Closes the transport immediately.
+		 */
+		@Override
+		public void close() {
+			lock.lock();
+			try {
+				if (this.closed) {
+					logger.debug("Session transport {} already closed", this.sessionId);
+					return;
+				}
+
+				this.closed = true;
+
+				// HttpServletStreamableServerTransportProvider.this.sessions.remove(this.sessionId);
+				this.asyncContext.complete();
+				logger.debug("Successfully completed async context for session {}", sessionId);
+			}
+			catch (Exception e) {
+				logger.warn("Failed to complete async context for session {}: {}", sessionId, e.getMessage());
+			}
+			finally {
+				lock.unlock();
+			}
+		}
+
+	}
+
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for creating instances of
+	 * {@link HttpServletStreamableServerTransportProvider}.
+	 */
+	public static class Builder {
+
+		private ObjectMapper objectMapper;
+
+		private String mcpEndpoint = "/mcp";
+
+		private boolean disallowDelete = false;
+
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
+		/**
+		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * messages.
+		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public Builder objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint URI where clients should send their JSON-RPC messages.
+		 * @param mcpEndpoint The MCP endpoint URI. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if mcpEndpoint is null
+		 */
+		public Builder mcpEndpoint(String mcpEndpoint) {
+			Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
+			this.mcpEndpoint = mcpEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets whether to disallow DELETE requests on the endpoint.
+		 * @param disallowDelete true to disallow DELETE requests, false otherwise
+		 * @return this builder instance
+		 */
+		public Builder disallowDelete(boolean disallowDelete) {
+			this.disallowDelete = disallowDelete;
+			return this;
+		}
+
+		/**
+		 * Sets the context extractor for extracting transport context from the request.
+		 * @param contextExtractor The context extractor to use. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "Context extractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
+		/**
+		 * Builds a new instance of {@link HttpServletStreamableServerTransportProvider}
+		 * with the configured settings.
+		 * @return A new HttpServletStreamableServerTransportProvider instance
+		 * @throws IllegalStateException if required parameters are not set
+		 */
+		public HttpServletStreamableServerTransportProvider build() {
+			Assert.notNull(this.objectMapper, "ObjectMapper must be set");
+			Assert.notNull(this.mcpEndpoint, "MCP endpoint must be set");
+
+			return new HttpServletStreamableServerTransportProvider(this.objectMapper, this.mcpEndpoint,
+					this.disallowDelete, this.contextExtractor);
+		}
+
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
new file mode 100644
index 000000000..687ff6ae9
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -0,0 +1,1271 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol.server;
+
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.awaitility.Awaitility.await;
+import static org.mockito.Mockito.mock;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Function;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
+import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
+import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
+import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
+import io.modelcontextprotocol.spec.McpSchema.Role;
+import io.modelcontextprotocol.spec.McpSchema.Root;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import net.javacrumbs.jsonunit.core.Option;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+public abstract class AbstractMcpClientServerIntegrationTests {
+
+	protected ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
+
+	abstract protected void prepareClients(int port, String mcpEndpoint);
+
+	abstract protected McpServer.AsyncSpecification prepareAsyncServerBuilder();
+
+	abstract protected McpServer.SyncSpecification prepareSyncServerBuilder();
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void simple(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1000))
+			.build();
+
+		try (
+				// Create client without sampling capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+					.requestTimeout(Duration.ofSeconds(1000))
+					.build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+		}
+		server.closeGracefully();
+	}
+
+	// ---------------------------------------
+	// Sampling Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateMessageWithoutSamplingCapabilities(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+				exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
+				return Mono.just(mock(CallToolResult.class));
+			})
+			.build();
+
+		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
+
+		try (
+				// Create client without sampling capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+					.build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+			try {
+				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class)
+					.hasMessage("Client must be configured with sampling capabilities");
+			}
+		}
+		server.closeGracefully();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateMessageSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		//@formatter:off		
+		var mcpServer = prepareAsyncServerBuilder()
+				.serverInfo("test-server", "1.0.0")
+				.tools(tool)
+				.build();
+
+		try (
+			var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+				.capabilities(ClientCapabilities.builder().sampling().build())
+				.sampling(samplingHandler)
+				.build()) {//@formatter:on
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull().isEqualTo(callResponse);
+		}
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws InterruptedException {
+
+		// Client
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build();
+
+		// Server
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(4))
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response).isEqualTo(callResponse);
+
+		mcpClient.close();
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateMessageWithRequestTimeoutFail(String clientType) throws InterruptedException {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function samplingHandler = request -> {
+			assertThat(request.messages()).hasSize(1);
+			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
+					CreateMessageResult.StopReason.STOP_SEQUENCE);
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build();
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
+					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
+							new McpSchema.TextContent("Test message"))))
+					.modelPreferences(ModelPreferences.builder()
+						.hints(List.of())
+						.costPriority(1.0)
+						.speedPriority(1.0)
+						.intelligencePriority(1.0)
+						.build())
+					.build();
+
+				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.role()).isEqualTo(Role.USER);
+					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+					assertThat(result.model()).isEqualTo("MockModelName");
+					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1))
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+		}).withMessageContaining("Timeout");
+
+		mcpClient.close();
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Elicitation Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				exchange.createElicitation(mock(McpSchema.ElicitRequest.class)).block();
+
+				return Mono.just(mock(CallToolResult.class));
+			})
+			.build();
+
+		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
+
+		try (
+				// Create client without elicitation capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+			try {
+				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class)
+					.hasMessage("Client must be configured with elicitation capabilities");
+			}
+		}
+		server.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateElicitationSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+
+			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
+					Map.of("message", request.message()));
+		};
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = McpSchema.ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
+
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+		}
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+			try {
+				TimeUnit.SECONDS.sleep(2);
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
+					Map.of("message", request.message()));
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build();
+
+		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
+				null);
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = McpSchema.ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
+					assertThat(result).isNotNull();
+					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+					assertThat(result.content().get("message")).isEqualTo("Test message");
+				}).verifyComplete();
+
+				return Mono.just(callResponse);
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(3))
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response).isEqualTo(callResponse);
+
+		mcpClient.closeGracefully();
+		mcpServer.closeGracefully().block();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testCreateElicitationWithRequestTimeoutFail(String clientType) {
+
+		var latch = new CountDownLatch(1);
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		Function elicitationHandler = request -> {
+			assertThat(request.message()).isNotEmpty();
+			assertThat(request.requestedSchema()).isNotNull();
+
+			try {
+				if (!latch.await(2, TimeUnit.SECONDS)) {
+					throw new RuntimeException("Timeout waiting for elicitation processing");
+				}
+			}
+			catch (InterruptedException e) {
+				throw new RuntimeException(e);
+			}
+			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
+		};
+
+		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build();
+
+		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+
+		AtomicReference resultRef = new AtomicReference<>();
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				var elicitationRequest = ElicitRequest.builder()
+					.message("Test message")
+					.requestedSchema(
+							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
+					.build();
+
+				return exchange.createElicitation(elicitationRequest)
+					.doOnNext(resultRef::set)
+					.then(Mono.just(callResponse));
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1)) // 1 second.
+			.tools(tool)
+			.build();
+
+		InitializeResult initResult = mcpClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+		}).withMessageContaining("within 1000ms");
+
+		ElicitResult elicitResult = resultRef.get();
+		assertThat(elicitResult).isNull();
+
+		mcpClient.closeGracefully();
+		mcpServer.closeGracefully().block();
+	}
+
+	// ---------------------------------------
+	// Roots Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testRootsSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(rootsRef.get()).isNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(roots);
+			});
+
+			// Remove a root
+			mcpClient.removeRoot(roots.get(0).uri());
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
+			});
+
+			// Add a new root
+			var root3 = new Root("uri3://", "root3");
+			mcpClient.addRoot(root3);
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testRootsWithoutCapability(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				exchange.listRoots(); // try to list roots
+
+				return mock(CallToolResult.class);
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().rootsChangeHandler((exchange, rootsUpdate) -> {
+		}).tools(tool).build();
+
+		try (
+				// Create client without roots capability
+				// No roots capability
+				var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().build()).build()) {
+
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			// Attempt to list roots should fail
+			try {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}
+			catch (McpError e) {
+				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
+			}
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testRootsNotificationWithEmptyRootsList(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(List.of()) // Empty roots list
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).isEmpty();
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testRootsWithMultipleHandlers(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"));
+
+		AtomicReference> rootsRef1 = new AtomicReference<>();
+		AtomicReference> rootsRef2 = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef1.set(rootsUpdate))
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef2.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef1.get()).containsAll(roots);
+				assertThat(rootsRef2.get()).containsAll(roots);
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testRootsServerCloseWithActiveSubscription(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		List roots = List.of(new Root("uri1://", "root1"));
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder()
+			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
+			.build();
+
+		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
+			.roots(roots)
+			.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			mcpClient.rootsListChangedNotification();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(roots);
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tools Tests
+	// ---------------------------------------
+
+	String emptyJsonSchema = """
+			{
+				"$schema": "http://json-schema.org/draft-07/schema#",
+				"type": "object",
+				"properties": {}
+			}
+			""";
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testToolCallSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				try {
+					HttpResponse response = HttpClient.newHttpClient()
+						.send(HttpRequest.newBuilder()
+							.uri(URI.create(
+									"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+							.GET()
+							.build(), HttpResponse.BodyHandlers.ofString());
+					String responseBody = response.body();
+					assertThat(responseBody).isNotBlank();
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+
+				return callResponse;
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull().isEqualTo(callResponse);
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpSyncServer mcpServer = prepareSyncServerBuilder()
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(McpServerFeatures.SyncToolSpecification.builder()
+				.tool(Tool.builder()
+					.name("tool1")
+					.description("tool1 description")
+					.inputSchema(emptyJsonSchema)
+					.build())
+				.callHandler((exchange, request) -> {
+					// We trigger a timeout on blocking read, raising an exception
+					Mono.never().block(Duration.ofSeconds(1));
+					return null;
+				})
+				.build())
+			.build();
+
+		try (var mcpClient = clientBuilder.requestTimeout(Duration.ofMillis(6666)).build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// We expect the tool call to fail immediately with the exception raised by
+			// the offending tool
+			// instead of getting back a timeout.
+			assertThatExceptionOfType(McpError.class)
+				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
+				.withMessageContaining("Timeout on blocking read");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testToolListChangeHandlingSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+				// perform a blocking call to a remote service
+				try {
+					HttpResponse response = HttpClient.newHttpClient()
+						.send(HttpRequest.newBuilder()
+							.uri(URI.create(
+									"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+							.GET()
+							.build(), HttpResponse.BodyHandlers.ofString());
+					String responseBody = response.body();
+					assertThat(responseBody).isNotBlank();
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+				return callResponse;
+			})
+			.build();
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
+			// perform a blocking call to a remote service
+			try {
+				HttpResponse response = HttpClient.newHttpClient()
+					.send(HttpRequest.newBuilder()
+						.uri(URI.create(
+								"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+						.GET()
+						.build(), HttpResponse.BodyHandlers.ofString());
+				String responseBody = response.body();
+				assertThat(responseBody).isNotBlank();
+			}
+			catch (Exception e) {
+				e.printStackTrace();
+			}
+
+			rootsRef.set(toolsUpdate);
+		}).build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(rootsRef.get()).isNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			mcpServer.notifyToolsListChanged();
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
+			});
+
+			// Remove a tool
+			mcpServer.removeTool("tool1");
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).isEmpty();
+			});
+
+			// Add a new tool
+			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
+				.tool(Tool.builder()
+					.name("tool2")
+					.description("tool2 description")
+					.inputSchema(emptyJsonSchema)
+					.build())
+				.callHandler((exchange, request) -> callResponse)
+				.build();
+
+			mcpServer.addTool(tool2);
+
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
+			});
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testInitialize(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var mcpServer = prepareSyncServerBuilder().build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testPingSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that uses ping functionality
+		AtomicReference executionOrder = new AtomicReference<>("");
+
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder()
+				.name("ping-async-test")
+				.description("Test ping async behavior")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				executionOrder.set(executionOrder.get() + "1");
+
+				// Test async ping behavior
+				return exchange.ping().doOnNext(result -> {
+
+					assertThat(result).isNotNull();
+					// Ping should return an empty object or map
+					assertThat(result).isInstanceOf(Map.class);
+
+					executionOrder.set(executionOrder.get() + "2");
+					assertThat(result).isNotNull();
+				}).then(Mono.fromCallable(() -> {
+					executionOrder.set(executionOrder.get() + "3");
+					return new CallToolResult("Async ping test completed", false);
+				}));
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that tests ping async behavior
+			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("ping-async-test", Map.of()));
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Async ping test completed");
+
+			// Verify execution order
+			assertThat(executionOrder.get()).isEqualTo("123");
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				String expression = (String) request.arguments().getOrDefault("expression", "2 + 3");
+				double result = evaluateExpression(expression);
+				return CallToolResult.builder()
+					.structuredContent(
+							Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			// In WebMVC, structured content is returned properly
+			if (response.structuredContent() != null) {
+				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+					.containsEntry("operation", "2 + 3")
+					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
+			}
+			else {
+				// Fallback to checking content if structured content is not available
+				assertThat(response.content()).isNotEmpty();
+			}
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputValidationFailure(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				// Return invalid structured output. Result should be number, missing
+				// operation
+				return CallToolResult.builder()
+					.addTextContent("Invalid calculation")
+					.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputMissingStructuredContent(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				// Return result without structured content but tool has output schema
+				return CallToolResult.builder().addTextContent("Calculation completed").build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputRuntimeToolAddition(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Start server without tools
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpServerFeatures.SyncToolSpecification toolSpec = McpServerFeatures.SyncToolSpecification.builder()
+				.tool(dynamicTool)
+				.callHandler((exchange, request) -> {
+					int count = (Integer) request.arguments().getOrDefault("count", 1);
+					return CallToolResult.builder()
+						.addTextContent("Dynamic tool executed " + count + " times")
+						.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+						.build();
+				})
+				.build();
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
new file mode 100644
index 000000000..327ec1b21
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import org.junit.jupiter.api.Timeout;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+
+/**
+ * Tests for {@link McpAsyncServer} using
+ * {@link HttpServletStreamableServerTransportProvider}.
+ *
+ * @author Christian Tzolov
+ */
+@Timeout(15)
+class HttpServletStreamableAsyncServerTests extends AbstractMcpAsyncServerTests {
+
+	protected McpStreamableServerTransportProvider createMcpTransportProvider() {
+		return HttpServletStreamableServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.mcpEndpoint("/mcp/message")
+			.build();
+	}
+
+	@Override
+	protected McpServer.AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(createMcpTransportProvider());
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
new file mode 100644
index 000000000..3377f98a6
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol.server;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.Duration;
+
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.SyncSpecification;
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+
+class HttpServletStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
+
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
+	private static final String MESSAGE_ENDPOINT = "/mcp/message";
+
+	private HttpServletStreamableServerTransportProvider mcpServerTransportProvider;
+
+	private Tomcat tomcat;
+
+	@BeforeEach
+	public void before() {
+		// Create and configure the transport provider
+		mcpServerTransportProvider = HttpServletStreamableServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.mcpEndpoint(MESSAGE_ENDPOINT)
+			.build();
+
+		tomcat = TomcatTestUtil.createTomcatServer("", PORT, mcpServerTransportProvider);
+		try {
+			tomcat.start();
+			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+						.endpoint(MESSAGE_ENDPOINT)
+						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
+	}
+
+	@Override
+	protected AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(this.mcpServerTransportProvider);
+	}
+
+	@Override
+	protected SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(this.mcpServerTransportProvider);
+	}
+
+	@AfterEach
+	public void after() {
+		if (mcpServerTransportProvider != null) {
+			mcpServerTransportProvider.closeGracefully().block();
+		}
+		if (tomcat != null) {
+			try {
+				tomcat.stop();
+				tomcat.destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
new file mode 100644
index 000000000..66fa2b2ac
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import org.junit.jupiter.api.Timeout;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+
+/**
+ * Tests for {@link McpSyncServer} using
+ * {@link HttpServletStreamableServerTransportProvider}.
+ *
+ * @author Christian Tzolov
+ */
+@Timeout(15)
+class HttpServletStreamableSyncServerTests extends AbstractMcpSyncServerTests {
+
+	protected McpStreamableServerTransportProvider createMcpTransportProvider() {
+		return HttpServletStreamableServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.mcpEndpoint("/mcp/message")
+			.build();
+	}
+
+	@Override
+	protected McpServer.SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(createMcpTransportProvider());
+	}
+
+}

From ae2fc8683b89c93b51ab1940f9d9e580c604cb9c Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Fri, 11 Jul 2025 18:55:47 +0200
Subject: [PATCH 022/125] Introduce HttpRequest.Builder customizer for
 HttpClient-based transport

- Minor improvement: speed up HttpClientSseClientTransportTests by
  reusing the MCP Server container across tests.
- Minor improvement: rename "messageSink" to "deliveredSink" in
  HttpClientStreamableHttpTransport#sendMessage
---
 .../transport/AsyncHttpRequestCustomizer.java |  52 +++
 .../HttpClientSseClientTransport.java         |  98 ++++--
 .../HttpClientStreamableHttpTransport.java    | 303 +++++++++++-------
 .../transport/SyncHttpRequestCustomizer.java  |  21 ++
 .../HttpClientSseClientTransportTests.java    | 100 +++++-
 ...HttpClientStreamableHttpTransportTest.java | 115 +++++++
 6 files changed, 539 insertions(+), 150 deletions(-)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/AsyncHttpRequestCustomizer.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/SyncHttpRequestCustomizer.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/AsyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/AsyncHttpRequestCustomizer.java
new file mode 100644
index 000000000..dee026d96
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/AsyncHttpRequestCustomizer.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+import org.reactivestreams.Publisher;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+import reactor.util.annotation.Nullable;
+
+/**
+ * Customize {@link HttpRequest.Builder} before executing the request, in either SSE or
+ * Streamable HTTP transport.
+ * 

+ * When used in a non-blocking context, implementations MUST be non-blocking.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+public interface AsyncHttpRequestCustomizer {
+
+	Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
+			@Nullable String body);
+
+	AsyncHttpRequestCustomizer NOOP = new Noop();
+
+	/**
+	 * Wrap a sync implementation in an async wrapper.
+	 * 

+	 * Do NOT wrap a blocking implementation for use in a non-blocking context. For a
+	 * blocking implementation, consider using {@link Schedulers#boundedElastic()}.
+	 */
+	static AsyncHttpRequestCustomizer fromSync(SyncHttpRequestCustomizer customizer) {
+		return (builder, method, uri, body) -> Mono.fromSupplier(() -> {
+			customizer.customize(builder, method, uri, body);
+			return builder;
+		});
+	}
+
+	class Noop implements AsyncHttpRequestCustomizer {
+
+		@Override
+		public Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
+				String body) {
+			return Mono.just(builder);
+		}
+
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index b610ad93a..39fb0d461 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 - 2024 the original author or authors.
+ * Copyright 2024 - 2025 the original author or authors.
  */
 package io.modelcontextprotocol.client.transport;
 
@@ -102,6 +102,11 @@ public class HttpClientSseClientTransport implements McpClientTransport {
 	 */
 	protected final Sinks.One messageEndpointSink = Sinks.one();
 
+	/**
+	 * Customizer to modify requests before they are executed.
+	 */
+	private final AsyncHttpRequestCustomizer httpRequestCustomizer;
+
 	/**
 	 * Creates a new transport instance with default HTTP client and object mapper.
 	 * @param baseUri the base URI of the MCP server
@@ -172,18 +177,38 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 	 * @param objectMapper the object mapper for JSON serialization/deserialization
 	 * @throws IllegalArgumentException if objectMapper, clientBuilder, or headers is null
 	 */
+	@Deprecated(forRemoval = true)
 	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
 			String sseEndpoint, ObjectMapper objectMapper) {
+		this(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper, AsyncHttpRequestCustomizer.NOOP);
+	}
+
+	/**
+	 * Creates a new transport instance with custom HTTP client builder, object mapper,
+	 * and headers.
+	 * @param httpClient the HTTP client to use
+	 * @param requestBuilder the HTTP request builder to use
+	 * @param baseUri the base URI of the MCP server
+	 * @param sseEndpoint the SSE endpoint path
+	 * @param objectMapper the object mapper for JSON serialization/deserialization
+	 * @param httpRequestCustomizer customizer for the requestBuilder before executing
+	 * requests
+	 * @throws IllegalArgumentException if objectMapper, clientBuilder, or headers is null
+	 */
+	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
+			String sseEndpoint, ObjectMapper objectMapper, AsyncHttpRequestCustomizer httpRequestCustomizer) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.hasText(baseUri, "baseUri must not be empty");
 		Assert.hasText(sseEndpoint, "sseEndpoint must not be empty");
 		Assert.notNull(httpClient, "httpClient must not be null");
 		Assert.notNull(requestBuilder, "requestBuilder must not be null");
+		Assert.notNull(httpRequestCustomizer, "httpRequestCustomizer must not be null");
 		this.baseUri = URI.create(baseUri);
 		this.sseEndpoint = sseEndpoint;
 		this.objectMapper = objectMapper;
 		this.httpClient = httpClient;
 		this.requestBuilder = requestBuilder;
+		this.httpRequestCustomizer = httpRequestCustomizer;
 	}
 
 	/**
@@ -213,6 +238,8 @@ public static class Builder {
 		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
 			.header("Content-Type", "application/json");
 
+		private AsyncHttpRequestCustomizer httpRequestCustomizer = AsyncHttpRequestCustomizer.NOOP;
+
 		/**
 		 * Creates a new builder instance.
 		 */
@@ -310,31 +337,66 @@ public Builder objectMapper(ObjectMapper objectMapper) {
 			return this;
 		}
 
+		/**
+		 * Sets the customizer for {@link HttpRequest.Builder}, to modify requests before
+		 * executing them.
+		 * 

+		 * This overrides the customizer from
+		 * {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}.
+		 * 

+		 * Do NOT use a blocking {@link SyncHttpRequestCustomizer} in a non-blocking
+		 * context. Use {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}
+		 * instead.
+		 * @param syncHttpRequestCustomizer the request customizer
+		 * @return this builder
+		 */
+		public Builder httpRequestCustomizer(SyncHttpRequestCustomizer syncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = AsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
+			return this;
+		}
+
+		/**
+		 * Sets the customizer for {@link HttpRequest.Builder}, to modify requests before
+		 * executing them.
+		 * 

+		 * This overrides the customizer from
+		 * {@link #httpRequestCustomizer(SyncHttpRequestCustomizer)}.
+		 * 

+		 * Do NOT use a blocking implementation in a non-blocking context.
+		 * @param asyncHttpRequestCustomizer the request customizer
+		 * @return this builder
+		 */
+		public Builder asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = asyncHttpRequestCustomizer;
+			return this;
+		}
+
 		/**
 		 * Builds a new {@link HttpClientSseClientTransport} instance.
 		 * @return a new transport instance
 		 */
 		public HttpClientSseClientTransport build() {
 			return new HttpClientSseClientTransport(clientBuilder.build(), requestBuilder, baseUri, sseEndpoint,
-					objectMapper);
+					objectMapper, httpRequestCustomizer);
 		}
 
 	}
 
 	@Override
 	public Mono connect(Function, Mono> handler) {
+		var uri = Utils.resolveUri(this.baseUri, this.sseEndpoint);
 
-		return Mono.create(sink -> {
-
-			HttpRequest request = requestBuilder.copy()
-				.uri(Utils.resolveUri(this.baseUri, this.sseEndpoint))
+		return Mono.defer(() -> {
+			var builder = requestBuilder.copy()
+				.uri(uri)
 				.header("Accept", "text/event-stream")
 				.header("Cache-Control", "no-cache")
-				.GET()
-				.build();
-
+				.GET();
+			return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null));
+		}).flatMap(requestBuilder -> Mono.create(sink -> {
 			Disposable connection = Flux.create(sseSink -> this.httpClient
-				.sendAsync(request, responseInfo -> ResponseSubscribers.sseToBodySubscriber(responseInfo, sseSink))
+				.sendAsync(requestBuilder.build(),
+						responseInfo -> ResponseSubscribers.sseToBodySubscriber(responseInfo, sseSink))
 				.exceptionallyCompose(e -> {
 					sseSink.error(e);
 					return CompletableFuture.failedFuture(e);
@@ -397,7 +459,7 @@ else if (MESSAGE_EVENT_TYPE.equals(responseEvent.sseEvent().event())) {
 				.subscribe();
 
 			this.sseSubscription.set(connection);
-		});
+		}));
 	}
 
 	/**
@@ -453,13 +515,13 @@ private Mono serializeMessage(final JSONRPCMessage message) {
 
 	private Mono> sendHttpPost(final String endpoint, final String body) {
 		final URI requestUri = Utils.resolveUri(baseUri, endpoint);
-		final HttpRequest request = this.requestBuilder.copy()
-			.uri(requestUri)
-			.POST(HttpRequest.BodyPublishers.ofString(body))
-			.build();
-
-		// TODO: why discard the body?
-		return Mono.fromFuture(httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString()));
+		return Mono.defer(() -> {
+			var builder = this.requestBuilder.copy().uri(requestUri).POST(HttpRequest.BodyPublishers.ofString(body));
+			return Mono.from(this.httpRequestCustomizer.customize(builder, "POST", requestUri, body));
+		}).flatMap(customizedBuilder -> {
+			var request = customizedBuilder.build();
+			return Mono.fromFuture(httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString()));
+		});
 	}
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index d8dd97f1e..799716584 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024-2024 the original author or authors.
+ * Copyright 2024-2025 the original author or authors.
  */
 
 package io.modelcontextprotocol.client.transport;
@@ -109,6 +109,8 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private final boolean resumableStreams;
 
+	private final AsyncHttpRequestCustomizer httpRequestCustomizer;
+
 	private final AtomicReference activeSession = new AtomicReference<>();
 
 	private final AtomicReference, Mono>> handler = new AtomicReference<>();
@@ -117,7 +119,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private HttpClientStreamableHttpTransport(ObjectMapper objectMapper, HttpClient httpClient,
 			HttpRequest.Builder requestBuilder, String baseUri, String endpoint, boolean resumableStreams,
-			boolean openConnectionOnStartup) {
+			boolean openConnectionOnStartup, AsyncHttpRequestCustomizer httpRequestCustomizer) {
 		this.objectMapper = objectMapper;
 		this.httpClient = httpClient;
 		this.requestBuilder = requestBuilder;
@@ -126,6 +128,7 @@ private HttpClientStreamableHttpTransport(ObjectMapper objectMapper, HttpClient
 		this.resumableStreams = resumableStreams;
 		this.openConnectionOnStartup = openConnectionOnStartup;
 		this.activeSession.set(createTransportSession());
+		this.httpRequestCustomizer = httpRequestCustomizer;
 	}
 
 	public static Builder builder(String baseUri) {
@@ -154,14 +157,18 @@ private DefaultMcpTransportSession createTransportSession() {
 	}
 
 	private Publisher createDelete(String sessionId) {
-		HttpRequest request = this.requestBuilder.copy()
-			.uri(Utils.resolveUri(this.baseUri, this.endpoint))
-			.header("Cache-Control", "no-cache")
-			.header("mcp-session-id", sessionId)
-			.DELETE()
-			.build();
-
-		return Mono.fromFuture(() -> this.httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString())).then();
+		var uri = Utils.resolveUri(this.baseUri, this.endpoint);
+		return Mono.defer(() -> {
+			var builder = this.requestBuilder.copy()
+				.uri(uri)
+				.header("Cache-Control", "no-cache")
+				.header("mcp-session-id", sessionId)
+				.DELETE();
+			return Mono.from(this.httpRequestCustomizer.customize(builder, "DELETE", uri, null));
+		}).flatMap(requestBuilder -> {
+			var request = requestBuilder.build();
+			return Mono.fromFuture(() -> this.httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString()));
+		}).then();
 	}
 
 	@Override
@@ -208,100 +215,110 @@ private Mono reconnect(McpTransportStream stream) {
 
 			final AtomicReference disposableRef = new AtomicReference<>();
 			final McpTransportSession transportSession = this.activeSession.get();
+			var uri = Utils.resolveUri(this.baseUri, this.endpoint);
 
-			HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
-
-			if (transportSession != null && transportSession.sessionId().isPresent()) {
-				requestBuilder = requestBuilder.header("mcp-session-id", transportSession.sessionId().get());
-			}
-
-			if (stream != null && stream.lastId().isPresent()) {
-				requestBuilder = requestBuilder.header("last-event-id", stream.lastId().get());
-			}
-
-			HttpRequest request = requestBuilder.uri(Utils.resolveUri(this.baseUri, this.endpoint))
-				.header("Accept", TEXT_EVENT_STREAM)
-				.header("Cache-Control", "no-cache")
-				.GET()
-				.build();
-
-			Disposable connection = Flux.create(sseSink -> this.httpClient
-				.sendAsync(request, responseInfo -> ResponseSubscribers.sseToBodySubscriber(responseInfo, sseSink))
-				.whenComplete((response, throwable) -> {
-					if (throwable != null) {
-						sseSink.error(throwable);
-					}
-					else {
-						logger.debug("SSE connection established successfully");
-					}
-				}))
-				.map(responseEvent -> (ResponseSubscribers.SseResponseEvent) responseEvent)
-				.flatMap(responseEvent -> {
-					int statusCode = responseEvent.responseInfo().statusCode();
-
-					if (statusCode >= 200 && statusCode < 300) {
+			Disposable connection = Mono.defer(() -> {
+				HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
 
-						if (MESSAGE_EVENT_TYPE.equals(responseEvent.sseEvent().event())) {
-							try {
-								// We don't support batching ATM and probably won't since
-								// the
-								// next version considers removing it.
-								McpSchema.JSONRPCMessage message = McpSchema
-									.deserializeJsonRpcMessage(this.objectMapper, responseEvent.sseEvent().data());
-
-								Tuple2, Iterable> idWithMessages = Tuples
-									.of(Optional.ofNullable(responseEvent.sseEvent().id()), List.of(message));
+				if (transportSession != null && transportSession.sessionId().isPresent()) {
+					requestBuilder = requestBuilder.header("mcp-session-id", transportSession.sessionId().get());
+				}
 
-								McpTransportStream sessionStream = stream != null ? stream
-										: new DefaultMcpTransportStream<>(this.resumableStreams, this::reconnect);
-								logger.debug("Connected stream {}", sessionStream.streamId());
+				if (stream != null && stream.lastId().isPresent()) {
+					requestBuilder = requestBuilder.header("last-event-id", stream.lastId().get());
+				}
 
-								return Flux.from(sessionStream.consumeSseStream(Flux.just(idWithMessages)));
+				var builder = requestBuilder.uri(uri)
+					.header("Accept", TEXT_EVENT_STREAM)
+					.header("Cache-Control", "no-cache")
+					.GET();
+				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null));
+			})
+				.flatMapMany(
+						requestBuilder -> Flux.create(
+								sseSink -> this.httpClient
+									.sendAsync(requestBuilder.build(),
+											responseInfo -> ResponseSubscribers.sseToBodySubscriber(responseInfo,
+													sseSink))
+									.whenComplete((response, throwable) -> {
+										if (throwable != null) {
+											sseSink.error(throwable);
+										}
+										else {
+											logger.debug("SSE connection established successfully");
+										}
+									}))
+							.map(responseEvent -> (ResponseSubscribers.SseResponseEvent) responseEvent)
+							.flatMap(responseEvent -> {
+								int statusCode = responseEvent.responseInfo().statusCode();
+
+								if (statusCode >= 200 && statusCode < 300) {
+
+									if (MESSAGE_EVENT_TYPE.equals(responseEvent.sseEvent().event())) {
+										try {
+											// We don't support batching ATM and probably
+											// won't since the next version considers
+											// removing it.
+											McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(
+													this.objectMapper, responseEvent.sseEvent().data());
+
+											Tuple2, Iterable> idWithMessages = Tuples
+												.of(Optional.ofNullable(responseEvent.sseEvent().id()),
+														List.of(message));
+
+											McpTransportStream sessionStream = stream != null ? stream
+													: new DefaultMcpTransportStream<>(this.resumableStreams,
+															this::reconnect);
+											logger.debug("Connected stream {}", sessionStream.streamId());
+
+											return Flux.from(sessionStream.consumeSseStream(Flux.just(idWithMessages)));
+
+										}
+										catch (IOException ioException) {
+											return Flux.error(
+													new McpError("Error parsing JSON-RPC message: "
+															+ responseEvent.sseEvent().data()));
+										}
+									}
+									else {
+										logger.debug("Received SSE event with type: {}", responseEvent.sseEvent());
+										return Flux.empty();
+									}
+								}
+								else if (statusCode == METHOD_NOT_ALLOWED) { // NotAllowed
+									logger
+										.debug("The server does not support SSE streams, using request-response mode.");
+									return Flux.empty();
+								}
+								else if (statusCode == NOT_FOUND) {
+									String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
+									McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
+											"Session not found for session ID: " + sessionIdRepresentation);
+									return Flux.error(exception);
+								}
+								else if (statusCode == BAD_REQUEST) {
+									String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
+									McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
+											"Session not found for session ID: " + sessionIdRepresentation);
+									return Flux.error(exception);
+								}
 
-							}
-							catch (IOException ioException) {
 								return Flux.error(new McpError(
-										"Error parsing JSON-RPC message: " + responseEvent.sseEvent().data()));
-							}
-						}
-						else {
-							logger.debug("Received SSE event with type: {}", responseEvent.sseEvent());
-							return Flux.empty();
-						}
-					}
-					else if (statusCode == METHOD_NOT_ALLOWED) { // NotAllowed
-						logger.debug("The server does not support SSE streams, using request-response mode.");
-						return Flux.empty();
-					}
-					else if (statusCode == NOT_FOUND) {
-						String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
-						McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
-								"Session not found for session ID: " + sessionIdRepresentation);
-						return Flux.error(exception);
-					}
-					else if (statusCode == BAD_REQUEST) {
-						String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
-						McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
-								"Session not found for session ID: " + sessionIdRepresentation);
-						return Flux.error(exception);
-					}
-
-					return Flux.error(
-							new McpError("Received unrecognized SSE event type: " + responseEvent.sseEvent().event()));
-
-				}).flatMap(jsonrpcMessage -> this.handler.get().apply(Mono.just(jsonrpcMessage)))
-				.onErrorMap(CompletionException.class, t -> t.getCause())
-				.onErrorComplete(t -> {
-					this.handleException(t);
-					return true;
-				})
-				.doFinally(s -> {
-					Disposable ref = disposableRef.getAndSet(null);
-					if (ref != null) {
-						transportSession.removeConnection(ref);
-					}
-				})
+										"Received unrecognized SSE event type: " + responseEvent.sseEvent().event()));
+							}).flatMap(
+											jsonrpcMessage -> this.handler.get().apply(Mono.just(jsonrpcMessage)))
+							.onErrorMap(CompletionException.class, t -> t.getCause())
+							.onErrorComplete(t -> {
+								this.handleException(t);
+								return true;
+							})
+							.doFinally(s -> {
+								Disposable ref = disposableRef.getAndSet(null);
+								if (ref != null) {
+									transportSession.removeConnection(ref);
+								}
+							}))
 				.contextWrite(ctx)
 				.subscribe();
 
@@ -347,31 +364,33 @@ public String toString(McpSchema.JSONRPCMessage message) {
 	}
 
 	public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
-		return Mono.create(messageSink -> {
+		return Mono.create(deliveredSink -> {
 			logger.debug("Sending message {}", sentMessage);
 
 			final AtomicReference disposableRef = new AtomicReference<>();
 			final McpTransportSession transportSession = this.activeSession.get();
 
-			HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
-
-			if (transportSession != null && transportSession.sessionId().isPresent()) {
-				requestBuilder = requestBuilder.header("mcp-session-id", transportSession.sessionId().get());
-			}
-
+			var uri = Utils.resolveUri(this.baseUri, this.endpoint);
 			String jsonBody = this.toString(sentMessage);
 
-			HttpRequest request = requestBuilder.uri(Utils.resolveUri(this.baseUri, this.endpoint))
-				.header("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
-				.header("Content-Type", APPLICATION_JSON)
-				.header("Cache-Control", "no-cache")
-				.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
-				.build();
+			Disposable connection = Mono.defer(() -> {
+				HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
 
-			Disposable connection = Flux.create(responseEventSink -> {
+				if (transportSession != null && transportSession.sessionId().isPresent()) {
+					requestBuilder = requestBuilder.header("mcp-session-id", transportSession.sessionId().get());
+				}
+
+				var builder = requestBuilder.uri(uri)
+					.header("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
+					.header("Content-Type", APPLICATION_JSON)
+					.header("Cache-Control", "no-cache")
+					.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
+				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, jsonBody));
+			}).flatMapMany(requestBuilder -> Flux.create(responseEventSink -> {
 
 				// Create the async request with proper body subscriber selection
-				Mono.fromFuture(this.httpClient.sendAsync(request, this.toSendMessageBodySubscriber(responseEventSink))
+				Mono.fromFuture(this.httpClient
+					.sendAsync(requestBuilder.build(), this.toSendMessageBodySubscriber(responseEventSink))
 					.whenComplete((response, throwable) -> {
 						if (throwable != null) {
 							responseEventSink.error(throwable);
@@ -381,13 +400,13 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 						}
 					})).onErrorMap(CompletionException.class, t -> t.getCause()).onErrorComplete().subscribe();
 
-			}).flatMap(responseEvent -> {
+			})).flatMap(responseEvent -> {
 				if (transportSession.markInitialized(
 						responseEvent.responseInfo().headers().firstValue("mcp-session-id").orElseGet(() -> null))) {
 					// Once we have a session, we try to open an async stream for
 					// the server to send notifications and requests out-of-band.
 
-					reconnect(null).contextWrite(messageSink.contextView()).subscribe();
+					reconnect(null).contextWrite(deliveredSink.contextView()).subscribe();
 				}
 
 				String sessionRepresentation = sessionIdOrPlaceholder(transportSession);
@@ -404,16 +423,18 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 
 					if (contentType.isBlank()) {
 						logger.debug("No content type returned for POST in session {}", sessionRepresentation);
-						// No content type means no response body, so we can just return
+						// No content type means no response body, so we can just
+						// return
 						// an empty stream
-						messageSink.success();
+						deliveredSink.success();
 						return Flux.empty();
 					}
 					else if (contentType.contains(TEXT_EVENT_STREAM)) {
 						return Flux.just(((ResponseSubscribers.SseResponseEvent) responseEvent).sseEvent())
 							.flatMap(sseEvent -> {
 								try {
-									// We don't support batching ATM and probably won't
+									// We don't support batching ATM and probably
+									// won't
 									// since the
 									// next version considers removing it.
 									McpSchema.JSONRPCMessage message = McpSchema
@@ -427,7 +448,7 @@ else if (contentType.contains(TEXT_EVENT_STREAM)) {
 
 									logger.debug("Connected stream {}", sessionStream.streamId());
 
-									messageSink.success();
+									deliveredSink.success();
 
 									return Flux.from(sessionStream.consumeSseStream(Flux.just(idWithMessages)));
 								}
@@ -438,7 +459,7 @@ else if (contentType.contains(TEXT_EVENT_STREAM)) {
 							});
 					}
 					else if (contentType.contains(APPLICATION_JSON)) {
-						messageSink.success();
+						deliveredSink.success();
 						String data = ((ResponseSubscribers.AggregateResponseEvent) responseEvent).data();
 						if (sentMessage instanceof McpSchema.JSONRPCNotification && Utils.hasText(data)) {
 							logger.warn("Notification: {} received non-compliant response: {}", sentMessage, data);
@@ -483,7 +504,7 @@ else if (statusCode == BAD_REQUEST) {
 					// handle the error first
 					this.handleException(t);
 					// inform the caller of sendMessage
-					messageSink.error(t);
+					deliveredSink.error(t);
 					return true;
 				})
 				.doFinally(s -> {
@@ -493,7 +514,7 @@ else if (statusCode == BAD_REQUEST) {
 						transportSession.removeConnection(ref);
 					}
 				})
-				.contextWrite(messageSink.contextView())
+				.contextWrite(deliveredSink.contextView())
 				.subscribe();
 
 			disposableRef.set(connection);
@@ -531,6 +552,8 @@ public static class Builder {
 
 		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder();
 
+		private AsyncHttpRequestCustomizer httpRequestCustomizer = AsyncHttpRequestCustomizer.NOOP;
+
 		/**
 		 * Creates a new builder with the specified base URI.
 		 * @param baseUri the base URI of the MCP server
@@ -633,6 +656,40 @@ public Builder openConnectionOnStartup(boolean openConnectionOnStartup) {
 			return this;
 		}
 
+		/**
+		 * Sets the customizer for {@link HttpRequest.Builder}, to modify requests before
+		 * executing them.
+		 * 

+		 * This overrides the customizer from
+		 * {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}.
+		 * 

+		 * Do NOT use a blocking {@link SyncHttpRequestCustomizer} in a non-blocking
+		 * context. Use {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}
+		 * instead.
+		 * @param syncHttpRequestCustomizer the request customizer
+		 * @return this builder
+		 */
+		public Builder httpRequestCustomizer(SyncHttpRequestCustomizer syncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = AsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
+			return this;
+		}
+
+		/**
+		 * Sets the customizer for {@link HttpRequest.Builder}, to modify requests before
+		 * executing them.
+		 * 

+		 * This overrides the customizer from
+		 * {@link #httpRequestCustomizer(SyncHttpRequestCustomizer)}.
+		 * 

+		 * Do NOT use a blocking implementation in a non-blocking context.
+		 * @param asyncHttpRequestCustomizer the request customizer
+		 * @return this builder
+		 */
+		public Builder asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = asyncHttpRequestCustomizer;
+			return this;
+		}
+
 		/**
 		 * Construct a fresh instance of {@link HttpClientStreamableHttpTransport} using
 		 * the current builder configuration.
@@ -642,7 +699,7 @@ public HttpClientStreamableHttpTransport build() {
 			ObjectMapper objectMapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 
 			return new HttpClientStreamableHttpTransport(objectMapper, clientBuilder.build(), requestBuilder, baseUri,
-					endpoint, resumableStreams, openConnectionOnStartup);
+					endpoint, resumableStreams, openConnectionOnStartup, httpRequestCustomizer);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/SyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/SyncHttpRequestCustomizer.java
new file mode 100644
index 000000000..72b6e6c1b
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/SyncHttpRequestCustomizer.java
@@ -0,0 +1,21 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+import reactor.util.annotation.Nullable;
+
+/**
+ * Customize {@link HttpRequest.Builder} before executing the request, either in SSE or
+ * Streamable HTTP transport.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+public interface SyncHttpRequestCustomizer {
+
+	void customize(HttpRequest.Builder builder, String method, URI endpoint, @Nullable String body);
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
index 31430543a..46b9207f6 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
@@ -17,10 +17,13 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCRequest;
+import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Timeout;
+import org.mockito.ArgumentCaptor;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
 import reactor.core.publisher.Mono;
@@ -28,9 +31,17 @@
 import reactor.test.StepVerifier;
 
 import org.springframework.http.codec.ServerSentEvent;
+import org.springframework.web.util.UriComponentsBuilder;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.clearInvocations;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
 
 /**
  * Tests for the {@link HttpClientSseClientTransport} class.
@@ -43,7 +54,7 @@ class HttpClientSseClientTransportTests {
 	static String host = "http://localhost:3001";
 
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -61,7 +72,7 @@ static class TestHttpClientSseClientTransport extends HttpClientSseClientTranspo
 		public TestHttpClientSseClientTransport(final String baseUri) {
 			super(HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build(),
 					HttpRequest.newBuilder().header("Content-Type", "application/json"), baseUri, "/sse",
-					new ObjectMapper());
+					new ObjectMapper(), AsyncHttpRequestCustomizer.NOOP);
 		}
 
 		public int getInboundMessageCount() {
@@ -80,15 +91,21 @@ public void simulateMessageEvent(String jsonMessage) {
 
 	}
 
-	void startContainer() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
+
+	}
+
+	@AfterAll
+	static void stopContainer() {
+		container.stop();
 	}
 
 	@BeforeEach
 	void setUp() {
-		startContainer();
 		transport = new TestHttpClientSseClientTransport(host);
 		transport.connect(Function.identity()).block();
 	}
@@ -98,11 +115,6 @@ void afterEach() {
 		if (transport != null) {
 			assertThatCode(() -> transport.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 		}
-		cleanup();
-	}
-
-	void cleanup() {
-		container.stop();
 	}
 
 	@Test
@@ -375,4 +387,74 @@ void testChainedCustomizations() {
 		customizedTransport.closeGracefully().block();
 	}
 
+	@Test
+	void testRequestCustomizer() {
+		var mockCustomizer = mock(SyncHttpRequestCustomizer.class);
+
+		// Create a transport with the customizer
+		var customizedTransport = HttpClientSseClientTransport.builder(host)
+			.httpRequestCustomizer(mockCustomizer)
+			.build();
+
+		// Connect
+		StepVerifier.create(customizedTransport.connect(Function.identity())).verifyComplete();
+
+		// Verify the customizer was called
+		verify(mockCustomizer).customize(any(), eq("GET"),
+				eq(UriComponentsBuilder.fromUriString(host).path("/sse").build().toUri()), isNull());
+		clearInvocations(mockCustomizer);
+
+		// Send test message
+		var testMessage = new JSONRPCRequest(McpSchema.JSONRPC_VERSION, "test-method", "test-id",
+				Map.of("key", "value"));
+
+		// Subscribe to messages and verify
+		StepVerifier.create(customizedTransport.sendMessage(testMessage)).verifyComplete();
+
+		// Verify the customizer was called
+		var uriArgumentCaptor = ArgumentCaptor.forClass(URI.class);
+		verify(mockCustomizer).customize(any(), eq("POST"), uriArgumentCaptor.capture(), eq(
+				"{\"jsonrpc\":\"2.0\",\"method\":\"test-method\",\"id\":\"test-id\",\"params\":{\"key\":\"value\"}}"));
+		assertThat(uriArgumentCaptor.getValue().toString()).startsWith(host + "/message?sessionId=");
+
+		// Clean up
+		customizedTransport.closeGracefully().block();
+	}
+
+	@Test
+	void testAsyncRequestCustomizer() {
+		var mockCustomizer = mock(AsyncHttpRequestCustomizer.class);
+		when(mockCustomizer.customize(any(), any(), any(), any()))
+			.thenAnswer(invocation -> Mono.just(invocation.getArguments()[0]));
+
+		// Create a transport with the customizer
+		var customizedTransport = HttpClientSseClientTransport.builder(host)
+			.asyncHttpRequestCustomizer(mockCustomizer)
+			.build();
+
+		// Connect
+		StepVerifier.create(customizedTransport.connect(Function.identity())).verifyComplete();
+
+		// Verify the customizer was called
+		verify(mockCustomizer).customize(any(), eq("GET"),
+				eq(UriComponentsBuilder.fromUriString(host).path("/sse").build().toUri()), isNull());
+		clearInvocations(mockCustomizer);
+
+		// Send test message
+		var testMessage = new JSONRPCRequest(McpSchema.JSONRPC_VERSION, "test-method", "test-id",
+				Map.of("key", "value"));
+
+		// Subscribe to messages and verify
+		StepVerifier.create(customizedTransport.sendMessage(testMessage)).verifyComplete();
+
+		// Verify the customizer was called
+		var uriArgumentCaptor = ArgumentCaptor.forClass(URI.class);
+		verify(mockCustomizer).customize(any(), eq("POST"), uriArgumentCaptor.capture(), eq(
+				"{\"jsonrpc\":\"2.0\",\"method\":\"test-method\",\"id\":\"test-id\",\"params\":{\"key\":\"value\"}}"));
+		assertThat(uriArgumentCaptor.getValue().toString()).startsWith(host + "/message?sessionId=");
+
+		// Clean up
+		customizedTransport.closeGracefully().block();
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
new file mode 100644
index 000000000..479468f63
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -0,0 +1,115 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.util.function.Consumer;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.testcontainers.containers.GenericContainer;
+import org.testcontainers.containers.wait.strategy.Wait;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * Tests for the {@link HttpClientStreamableHttpTransport} class.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+class HttpClientStreamableHttpTransportTest {
+
+	static String host = "http://localhost:3001";
+
+	@SuppressWarnings("resource")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+		.withCommand("node dist/index.js streamableHttp")
+		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
+		.withExposedPorts(3001)
+		.waitingFor(Wait.forHttp("/").forStatusCode(404));
+
+	@BeforeAll
+	static void startContainer() {
+		container.start();
+		int port = container.getMappedPort(3001);
+		host = "http://" + container.getHost() + ":" + port;
+	}
+
+	@AfterAll
+	static void stopContainer() {
+		container.stop();
+	}
+
+	void withTransport(HttpClientStreamableHttpTransport transport, Consumer c) {
+		try {
+			c.accept(transport);
+		}
+		finally {
+			StepVerifier.create(transport.closeGracefully()).verifyComplete();
+		}
+	}
+
+	@Test
+	void testRequestCustomizer() throws URISyntaxException {
+		var uri = new URI(host + "/mcp");
+		var mockRequestCustomizer = mock(SyncHttpRequestCustomizer.class);
+
+		var transport = HttpClientStreamableHttpTransport.builder(host)
+			.httpRequestCustomizer(mockRequestCustomizer)
+			.build();
+
+		withTransport(transport, (t) -> {
+			// Send test message
+			var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
+					McpSchema.ClientCapabilities.builder().roots(true).build(),
+					new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+			var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
+					"test-id", initializeRequest);
+
+			StepVerifier.create(t.sendMessage(testMessage)).verifyComplete();
+
+			// Verify the customizer was called
+			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("GET"), eq(uri), eq(
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
+		});
+	}
+
+	@Test
+	void testAsyncRequestCustomizer() throws URISyntaxException {
+		var uri = new URI(host + "/mcp");
+		var mockRequestCustomizer = mock(AsyncHttpRequestCustomizer.class);
+		when(mockRequestCustomizer.customize(any(), any(), any(), any()))
+			.thenAnswer(invocation -> Mono.just(invocation.getArguments()[0]));
+
+		var transport = HttpClientStreamableHttpTransport.builder(host)
+			.asyncHttpRequestCustomizer(mockRequestCustomizer)
+			.build();
+
+		withTransport(transport, (t) -> {
+			// Send test message
+			var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
+					McpSchema.ClientCapabilities.builder().roots(true).build(),
+					new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+			var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
+					"test-id", initializeRequest);
+
+			StepVerifier.create(t.sendMessage(testMessage)).verifyComplete();
+
+			// Verify the customizer was called
+			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("GET"), eq(uri), eq(
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
+		});
+	}
+
+}

From ee2c891ccafe929d4828839bf14d06d7123624d9 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Wed, 30 Jul 2025 10:38:07 +0200
Subject: [PATCH 023/125] feat: implement MCP-compliant keep-alive
 functionality for server transports

- Add KeepAliveScheduler utility class for configurable periodic session pings
- Integrate keep-alive support in WebFlux, WebMVC, and HttpServlet SSE transport providers
- Add keepAliveInterval configuration option to all transport provider builders
- Deprecate existing constructors in favor of builder pattern with enhanced configuration
- Update graceful shutdown to properly clean up keep-alive schedulers
- Add unit tests for KeepAliveScheduler functionality

Implements MCP specification recommendations for connection health detection:
- Configurable ping frequency to suit different network environments
- Optional keep-alive (disabled by default) to avoid excessive network overhead
- Proper resource cleanup to prevent connection leaks

https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/ping#implementation-considerations

Resolves: #414, #158
Replaces #353

Signed-off-by: Christian Tzolov 
---
 .../WebFluxSseServerTransportProvider.java    |  83 ++++-
 ...FluxStreamableServerTransportProvider.java |  42 ++-
 .../WebMvcSseServerTransportProvider.java     | 158 ++++++++-
 ...bMvcStreamableServerTransportProvider.java |  40 ++-
 .../client/McpAsyncClient.java                |   7 +-
 ...HttpServletSseServerTransportProvider.java |  70 +++-
 ...vletStreamableServerTransportProvider.java |  46 ++-
 .../spec/McpStreamableServerSession.java      |  23 +-
 .../util/KeepAliveScheduler.java              | 216 +++++++++++++
 ...HttpServletStreamableIntegrationTests.java |   1 +
 .../util/KeepAliveSchedulerTests.java         | 303 ++++++++++++++++++
 11 files changed, 954 insertions(+), 35 deletions(-)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index fde067f03..b1b5246c8 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -1,6 +1,7 @@
 package io.modelcontextprotocol.server.transport;
 
 import java.io.IOException;
+import java.time.Duration;
 import java.util.concurrent.ConcurrentHashMap;
 
 import com.fasterxml.jackson.core.type.TypeReference;
@@ -11,6 +12,8 @@
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.KeepAliveScheduler;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import reactor.core.Exceptions;
@@ -109,6 +112,12 @@ public class WebFluxSseServerTransportProvider implements McpServerTransportProv
 	 */
 	private volatile boolean isClosing = false;
 
+	/**
+	 * Keep-alive scheduler for managing session pings. Activated if keepAliveInterval is
+	 * set. Disabled by default.
+	 */
+	private KeepAliveScheduler keepAliveScheduler;
+
 	/**
 	 * Constructs a new WebFlux SSE server transport provider instance with the default
 	 * SSE endpoint.
@@ -118,7 +127,10 @@ public class WebFluxSseServerTransportProvider implements McpServerTransportProv
 	 * messages. This endpoint will be communicated to clients during SSE connection
 	 * setup. Must not be null.
 	 * @throws IllegalArgumentException if either parameter is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint) {
 		this(objectMapper, messageEndpoint, DEFAULT_SSE_ENDPOINT);
 	}
@@ -131,7 +143,10 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String messa
 	 * messages. This endpoint will be communicated to clients during SSE connection
 	 * setup. Must not be null.
 	 * @throws IllegalArgumentException if either parameter is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint) {
 		this(objectMapper, DEFAULT_BASE_URL, messageEndpoint, sseEndpoint);
 	}
@@ -145,9 +160,32 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String messa
 	 * messages. This endpoint will be communicated to clients during SSE connection
 	 * setup. Must not be null.
 	 * @throws IllegalArgumentException if either parameter is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint) {
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null);
+	}
+
+	/**
+	 * Constructs a new WebFlux SSE server transport provider instance.
+	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * of MCP messages. Must not be null.
+	 * @param baseUrl webflux message base path
+	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
+	 * messages. This endpoint will be communicated to clients during SSE connection
+	 * setup. Must not be null.
+	 * @param sseEndpoint The SSE endpoint path. Must not be null.
+	 * @param keepAliveInterval The interval for sending keep-alive pings to clients.
+	 * @throws IllegalArgumentException if either parameter is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
+	 */
+	@Deprecated
+	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+			String sseEndpoint, Duration keepAliveInterval) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.notNull(baseUrl, "Message base path must not be null");
 		Assert.notNull(messageEndpoint, "Message endpoint must not be null");
@@ -161,6 +199,17 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseU
 			.GET(this.sseEndpoint, this::handleSseConnection)
 			.POST(this.messageEndpoint, this::handleMessage)
 			.build();
+
+		if (keepAliveInterval != null) {
+
+			this.keepAliveScheduler = KeepAliveScheduler
+				.builder(() -> (isClosing) ? Flux.empty() : Flux.fromIterable(sessions.values()))
+				.initialDelay(keepAliveInterval)
+				.interval(keepAliveInterval)
+				.build();
+
+			this.keepAliveScheduler.start();
+		}
 	}
 
 	@Override
@@ -209,15 +258,6 @@ public Mono notifyClients(String method, Object params) {
 	/**
 	 * Initiates a graceful shutdown of all the sessions. This method ensures all active
 	 * sessions are properly closed and cleaned up.
-	 *
-	 * 

-	 * The shutdown process:
-	 * 
    
-	 * 
  • Marks the transport as closing to prevent new connections
    • 
-	 * 
  • Closes each active session
    • 
-	 * 
  • Removes closed sessions from the sessions map
    • 
-	 * 
  • Times out after 5 seconds if shutdown takes too long
    • 
-	 * 

 	 * @return A Mono that completes when all sessions have been closed
 	 */
 	@Override
@@ -225,7 +265,14 @@ public Mono closeGracefully() {
 		return Flux.fromIterable(sessions.values())
 			.doFirst(() -> logger.debug("Initiating graceful shutdown with {} active sessions", sessions.size()))
 			.flatMap(McpServerSession::closeGracefully)
-			.then();
+			.then()
+			.doOnSuccess(v -> {
+				logger.debug("Graceful shutdown completed");
+				sessions.clear();
+				if (this.keepAliveScheduler != null) {
+					this.keepAliveScheduler.shutdown();
+				}
+			});
 	}
 
 	/**
@@ -396,6 +443,8 @@ public static class Builder {
 
 		private String sseEndpoint = DEFAULT_SSE_ENDPOINT;
 
+		private Duration keepAliveInterval;
+
 		/**
 		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
@@ -446,6 +495,17 @@ public Builder sseEndpoint(String sseEndpoint) {
 			return this;
 		}
 
+		/**
+		 * Sets the interval for sending keep-alive pings to clients.
+		 * @param keepAliveInterval The keep-alive interval duration. If null, keep-alive
+		 * is disabled.
+		 * @return this builder instance
+		 */
+		public Builder keepAliveInterval(Duration keepAliveInterval) {
+			this.keepAliveInterval = keepAliveInterval;
+			return this;
+		}
+
 		/**
 		 * Builds a new instance of {@link WebFluxSseServerTransportProvider} with the
 		 * configured settings.
@@ -456,7 +516,8 @@ public WebFluxSseServerTransportProvider build() {
 			Assert.notNull(objectMapper, "ObjectMapper must be set");
 			Assert.notNull(messageEndpoint, "Message endpoint must be set");
 
-			return new WebFluxSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint);
+			return new WebFluxSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
+					keepAliveInterval);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index e277e4749..79224a57d 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -12,6 +12,8 @@
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.KeepAliveScheduler;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpStatus;
@@ -28,6 +30,7 @@
 import reactor.core.publisher.Mono;
 
 import java.io.IOException;
+import java.time.Duration;
 import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
 
@@ -58,8 +61,11 @@ public class WebFluxStreamableServerTransportProvider implements McpStreamableSe
 
 	private volatile boolean isClosing = false;
 
+	private KeepAliveScheduler keepAliveScheduler;
+
 	private WebFluxStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
-			McpTransportContextExtractor contextExtractor, boolean disallowDelete) {
+			McpTransportContextExtractor contextExtractor, boolean disallowDelete,
+			Duration keepAliveInterval) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.notNull(mcpEndpoint, "Message endpoint must not be null");
 		Assert.notNull(contextExtractor, "Context extractor must not be null");
@@ -73,6 +79,20 @@ private WebFluxStreamableServerTransportProvider(ObjectMapper objectMapper, Stri
 			.POST(this.mcpEndpoint, this::handlePost)
 			.DELETE(this.mcpEndpoint, this::handleDelete)
 			.build();
+
+		if (keepAliveInterval != null) {
+			this.keepAliveScheduler = KeepAliveScheduler
+				.builder(() -> (isClosing) ? Flux.empty() : Flux.fromIterable(this.sessions.values()))
+				.initialDelay(keepAliveInterval)
+				.interval(keepAliveInterval)
+				.build();
+
+			this.keepAliveScheduler.start();
+		}
+		else {
+			logger.warn("Keep-alive interval is not set or invalid. No keep-alive will be scheduled.");
+		}
+
 	}
 
 	@Override
@@ -105,6 +125,11 @@ public Mono closeGracefully() {
 				.doFirst(() -> logger.debug("Initiating graceful shutdown with {} active sessions", sessions.size()))
 				.flatMap(McpStreamableServerSession::closeGracefully)
 				.then();
+		}).then().doOnSuccess(v -> {
+			sessions.clear();
+			if (this.keepAliveScheduler != null) {
+				this.keepAliveScheduler.shutdown();
+			}
 		});
 	}
 
@@ -368,6 +393,8 @@ public static class Builder {
 
 		private boolean disallowDelete;
 
+		private Duration keepAliveInterval;
+
 		private Builder() {
 			// used by a static method
 		}
@@ -424,6 +451,17 @@ public Builder disallowDelete(boolean disallowDelete) {
 			return this;
 		}
 
+		/**
+		 * Sets the keep-alive interval for the server transport.
+		 * @param keepAliveInterval The interval for sending keep-alive messages. If null,
+		 * no keep-alive will be scheduled.
+		 * @return this builder instance
+		 */
+		public Builder keepAliveInterval(Duration keepAliveInterval) {
+			this.keepAliveInterval = keepAliveInterval;
+			return this;
+		}
+
 		/**
 		 * Builds a new instance of {@link WebFluxStreamableServerTransportProvider} with
 		 * the configured settings.
@@ -435,7 +473,7 @@ public WebFluxStreamableServerTransportProvider build() {
 			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
 
 			return new WebFluxStreamableServerTransportProvider(objectMapper, mcpEndpoint, contextExtractor,
-					disallowDelete);
+					disallowDelete, keepAliveInterval);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index 5aa89d529..b90f9fb3d 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -18,6 +18,8 @@
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.KeepAliveScheduler;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
@@ -107,6 +109,8 @@ public class WebMvcSseServerTransportProvider implements McpServerTransportProvi
 	 */
 	private volatile boolean isClosing = false;
 
+	private KeepAliveScheduler keepAliveScheduler;
+
 	/**
 	 * Constructs a new WebMvcSseServerTransportProvider instance with the default SSE
 	 * endpoint.
@@ -116,7 +120,10 @@ public class WebMvcSseServerTransportProvider implements McpServerTransportProvi
 	 * messages via HTTP POST. This endpoint will be communicated to clients through the
 	 * SSE connection's initial endpoint event.
 	 * @throws IllegalArgumentException if either objectMapper or messageEndpoint is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint) {
 		this(objectMapper, messageEndpoint, DEFAULT_SSE_ENDPOINT);
 	}
@@ -130,7 +137,10 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String messag
 	 * SSE connection's initial endpoint event.
 	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
 	 * @throws IllegalArgumentException if any parameter is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint) {
 		this(objectMapper, "", messageEndpoint, sseEndpoint);
 	}
@@ -146,9 +156,33 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String messag
 	 * SSE connection's initial endpoint event.
 	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
 	 * @throws IllegalArgumentException if any parameter is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint) {
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null);
+	}
+
+	/**
+	 * Constructs a new WebMvcSseServerTransportProvider instance.
+	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * of messages.
+	 * @param baseUrl The base URL for the message endpoint, used to construct the full
+	 * endpoint URL for clients.
+	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
+	 * messages via HTTP POST. This endpoint will be communicated to clients through the
+	 * SSE connection's initial endpoint event.
+	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
+	 * * @param keepAliveInterval The interval for sending keep-alive messages to
+	 * @throws IllegalArgumentException if any parameter is null
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
+	 */
+	@Deprecated
+	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+			String sseEndpoint, Duration keepAliveInterval) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.notNull(baseUrl, "Message base URL must not be null");
 		Assert.notNull(messageEndpoint, "Message endpoint must not be null");
@@ -162,6 +196,17 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUr
 			.GET(this.sseEndpoint, this::handleSseConnection)
 			.POST(this.messageEndpoint, this::handleMessage)
 			.build();
+
+		if (keepAliveInterval != null) {
+
+			this.keepAliveScheduler = KeepAliveScheduler
+				.builder(() -> (isClosing) ? Flux.empty() : Flux.fromIterable(sessions.values()))
+				.initialDelay(keepAliveInterval)
+				.interval(keepAliveInterval)
+				.build();
+
+			this.keepAliveScheduler.start();
+		}
 	}
 
 	@Override
@@ -209,10 +254,13 @@ public Mono closeGracefully() {
 		return Flux.fromIterable(sessions.values()).doFirst(() -> {
 			this.isClosing = true;
 			logger.debug("Initiating graceful shutdown with {} active sessions", sessions.size());
-		})
-			.flatMap(McpServerSession::closeGracefully)
-			.then()
-			.doOnSuccess(v -> logger.debug("Graceful shutdown completed"));
+		}).flatMap(McpServerSession::closeGracefully).then().doOnSuccess(v -> {
+			logger.debug("Graceful shutdown completed");
+			sessions.clear();
+			if (this.keepAliveScheduler != null) {
+				this.keepAliveScheduler.shutdown();
+			}
+		});
 	}
 
 	/**
@@ -435,4 +483,106 @@ public void close() {
 
 	}
 
+	/**
+	 * Creates a new Builder instance for configuring and creating instances of
+	 * WebMvcSseServerTransportProvider.
+	 * @return A new Builder instance
+	 */
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for creating instances of WebMvcSseServerTransportProvider.
+	 * 

+	 * This builder provides a fluent API for configuring and creating instances of
+	 * WebMvcSseServerTransportProvider with custom settings.
+	 */
+	public static class Builder {
+
+		private ObjectMapper objectMapper = new ObjectMapper();
+
+		private String baseUrl = "";
+
+		private String messageEndpoint;
+
+		private String sseEndpoint = DEFAULT_SSE_ENDPOINT;
+
+		private Duration keepAliveInterval;
+
+		/**
+		 * Sets the JSON object mapper to use for message serialization/deserialization.
+		 * @param objectMapper The object mapper to use
+		 * @return This builder instance for method chaining
+		 */
+		public Builder objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the base URL for the server transport.
+		 * @param baseUrl The base URL to use
+		 * @return This builder instance for method chaining
+		 */
+		public Builder baseUrl(String baseUrl) {
+			Assert.notNull(baseUrl, "Base URL must not be null");
+			this.baseUrl = baseUrl;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint path where clients will send their messages.
+		 * @param messageEndpoint The message endpoint path
+		 * @return This builder instance for method chaining
+		 */
+		public Builder messageEndpoint(String messageEndpoint) {
+			Assert.hasText(messageEndpoint, "Message endpoint must not be empty");
+			this.messageEndpoint = messageEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint path where clients will establish SSE connections.
+		 * 

+		 * If not specified, the default value of {@link #DEFAULT_SSE_ENDPOINT} will be
+		 * used.
+		 * @param sseEndpoint The SSE endpoint path
+		 * @return This builder instance for method chaining
+		 */
+		public Builder sseEndpoint(String sseEndpoint) {
+			Assert.hasText(sseEndpoint, "SSE endpoint must not be empty");
+			this.sseEndpoint = sseEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets the interval for keep-alive pings.
+		 * 

+		 * If not specified, keep-alive pings will be disabled.
+		 * @param keepAliveInterval The interval duration for keep-alive pings
+		 * @return This builder instance for method chaining
+		 */
+		public Builder keepAliveInterval(Duration keepAliveInterval) {
+			this.keepAliveInterval = keepAliveInterval;
+			return this;
+		}
+
+		/**
+		 * Builds a new instance of WebMvcSseServerTransportProvider with the configured
+		 * settings.
+		 * @return A new WebMvcSseServerTransportProvider instance
+		 * @throws IllegalStateException if objectMapper or messageEndpoint is not set
+		 */
+		public WebMvcSseServerTransportProvider build() {
+			if (messageEndpoint == null) {
+				throw new IllegalStateException("MessageEndpoint must be set");
+			}
+			return new WebMvcSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
+					keepAliveInterval);
+		}
+
+	}
+
 }
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index d14a51d87..391aa3e8d 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -33,6 +33,8 @@
 import io.modelcontextprotocol.spec.McpStreamableServerTransport;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.KeepAliveScheduler;
+import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
 /**
@@ -101,6 +103,8 @@ public class WebMvcStreamableServerTransportProvider implements McpStreamableSer
 	 */
 	private volatile boolean isClosing = false;
 
+	private KeepAliveScheduler keepAliveScheduler;
+
 	/**
 	 * Constructs a new WebMvcStreamableServerTransportProvider instance.
 	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
@@ -113,7 +117,8 @@ public class WebMvcStreamableServerTransportProvider implements McpStreamableSer
 	 * @throws IllegalArgumentException if any parameter is null
 	 */
 	private WebMvcStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
-			boolean disallowDelete, McpTransportContextExtractor contextExtractor) {
+			boolean disallowDelete, McpTransportContextExtractor contextExtractor,
+			Duration keepAliveInterval) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
 		Assert.notNull(contextExtractor, "McpTransportContextExtractor must not be null");
@@ -127,6 +132,19 @@ private WebMvcStreamableServerTransportProvider(ObjectMapper objectMapper, Strin
 			.POST(this.mcpEndpoint, this::handlePost)
 			.DELETE(this.mcpEndpoint, this::handleDelete)
 			.build();
+
+		if (keepAliveInterval != null) {
+			this.keepAliveScheduler = KeepAliveScheduler
+				.builder(() -> (isClosing) ? Flux.empty() : Flux.fromIterable(this.sessions.values()))
+				.initialDelay(keepAliveInterval)
+				.interval(keepAliveInterval)
+				.build();
+
+			this.keepAliveScheduler.start();
+		}
+		else {
+			logger.warn("Keep-alive interval is not set or invalid. No keep-alive will be scheduled.");
+		}
 	}
 
 	@Override
@@ -184,6 +202,10 @@ public Mono closeGracefully() {
 
 			this.sessions.clear();
 			logger.debug("Graceful shutdown completed");
+		}).then().doOnSuccess(v -> {
+			if (this.keepAliveScheduler != null) {
+				this.keepAliveScheduler.shutdown();
+			}
 		});
 	}
 
@@ -584,6 +606,8 @@ public static class Builder {
 
 		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
 
+		private Duration keepAliveInterval;
+
 		/**
 		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
@@ -635,6 +659,18 @@ public Builder contextExtractor(McpTransportContextExtractor cont
 			return this;
 		}
 
+		/**
+		 * Sets the keep-alive interval for the transport. If set, a keep-alive scheduler
+		 * will be created to periodically check and send keep-alive messages to clients.
+		 * @param keepAliveInterval The interval duration for keep-alive messages, or null
+		 * to disable keep-alive
+		 * @return this builder instance
+		 */
+		public Builder keepAliveInterval(Duration keepAliveInterval) {
+			this.keepAliveInterval = keepAliveInterval;
+			return this;
+		}
+
 		/**
 		 * Builds a new instance of {@link WebMvcStreamableServerTransportProvider} with
 		 * the configured settings.
@@ -646,7 +682,7 @@ public WebMvcStreamableServerTransportProvider build() {
 			Assert.notNull(this.mcpEndpoint, "MCP endpoint must be set");
 
 			return new WebMvcStreamableServerTransportProvider(this.objectMapper, this.mcpEndpoint, this.disallowDelete,
-					this.contextExtractor);
+					this.contextExtractor, this.keepAliveInterval);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 9e861deba..405e7123f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -4,6 +4,8 @@
 package io.modelcontextprotocol.client;
 
 import java.time.Duration;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
@@ -174,7 +176,10 @@ public class McpAsyncClient {
 		Map> requestHandlers = new HashMap<>();
 
 		// Ping MUST respond with an empty data, but not NULL response.
-		requestHandlers.put(McpSchema.METHOD_PING, params -> Mono.just(Map.of()));
+		requestHandlers.put(McpSchema.METHOD_PING, params -> {
+			logger.debug("Received ping: {}", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
+			return Mono.just(Map.of());
+		});
 
 		// Roots List Request Handler
 		if (this.clientCapabilities.roots() != null) {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index afdbff472..5c0b85f26 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -6,6 +6,7 @@
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.PrintWriter;
+import java.time.Duration;
 import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
@@ -19,6 +20,7 @@
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.KeepAliveScheduler;
 import jakarta.servlet.AsyncContext;
 import jakarta.servlet.ServletException;
 import jakarta.servlet.annotation.WebServlet;
@@ -103,6 +105,12 @@ public class HttpServletSseServerTransportProvider extends HttpServlet implement
 	/** Session factory for creating new sessions */
 	private McpServerSession.Factory sessionFactory;
 
+	/**
+	 * Keep-alive scheduler for managing session pings. Activated if keepAliveInterval is
+	 * set. Disabled by default.
+	 */
+	private KeepAliveScheduler keepAliveScheduler;
+
 	/**
 	 * Creates a new HttpServletSseServerTransportProvider instance with a custom SSE
 	 * endpoint.
@@ -110,7 +118,10 @@ public class HttpServletSseServerTransportProvider extends HttpServlet implement
 	 * serialization/deserialization
 	 * @param messageEndpoint The endpoint path where clients will send their messages
 	 * @param sseEndpoint The endpoint path where clients will establish SSE connections
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint,
 			String sseEndpoint) {
 		this(objectMapper, DEFAULT_BASE_URL, messageEndpoint, sseEndpoint);
@@ -124,13 +135,47 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String m
 	 * @param baseUrl The base URL for the server transport
 	 * @param messageEndpoint The endpoint path where clients will send their messages
 	 * @param sseEndpoint The endpoint path where clients will establish SSE connections
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
 	 */
+	@Deprecated
 	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint) {
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null);
+	}
+
+	/**
+	 * Creates a new HttpServletSseServerTransportProvider instance with a custom SSE
+	 * endpoint.
+	 * @param objectMapper The JSON object mapper to use for message
+	 * serialization/deserialization
+	 * @param baseUrl The base URL for the server transport
+	 * @param messageEndpoint The endpoint path where clients will send their messages
+	 * @param sseEndpoint The endpoint path where clients will establish SSE connections
+	 * @param keepAliveInterval The interval for keep-alive pings, or null to disable
+	 * keep-alive functionality
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
+	 */
+	@Deprecated
+	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+			String sseEndpoint, Duration keepAliveInterval) {
+
 		this.objectMapper = objectMapper;
 		this.baseUrl = baseUrl;
 		this.messageEndpoint = messageEndpoint;
 		this.sseEndpoint = sseEndpoint;
+
+		if (keepAliveInterval != null) {
+
+			this.keepAliveScheduler = KeepAliveScheduler
+				.builder(() -> (isClosing.get()) ? Flux.empty() : Flux.fromIterable(sessions.values()))
+				.initialDelay(keepAliveInterval)
+				.interval(keepAliveInterval)
+				.build();
+
+			this.keepAliveScheduler.start();
+		}
 	}
 
 	/**
@@ -324,7 +369,13 @@ public Mono closeGracefully() {
 		isClosing.set(true);
 		logger.debug("Initiating graceful shutdown with {} active sessions", sessions.size());
 
-		return Flux.fromIterable(sessions.values()).flatMap(McpServerSession::closeGracefully).then();
+		return Flux.fromIterable(sessions.values()).flatMap(McpServerSession::closeGracefully).then().doOnSuccess(v -> {
+			sessions.clear();
+			logger.debug("Graceful shutdown completed");
+			if (this.keepAliveScheduler != null) {
+				this.keepAliveScheduler.shutdown();
+			}
+		});
 	}
 
 	/**
@@ -475,6 +526,8 @@ public static class Builder {
 
 		private String sseEndpoint = DEFAULT_SSE_ENDPOINT;
 
+		private Duration keepAliveInterval;
+
 		/**
 		 * Sets the JSON object mapper to use for message serialization/deserialization.
 		 * @param objectMapper The object mapper to use
@@ -522,6 +575,18 @@ public Builder sseEndpoint(String sseEndpoint) {
 			return this;
 		}
 
+		/**
+		 * Sets the interval for keep-alive pings.
+		 * 

+		 * If not specified, keep-alive pings will be disabled.
+		 * @param keepAliveInterval The interval duration for keep-alive pings
+		 * @return This builder instance for method chaining
+		 */
+		public Builder keepAliveInterval(Duration keepAliveInterval) {
+			this.keepAliveInterval = keepAliveInterval;
+			return this;
+		}
+
 		/**
 		 * Builds a new instance of HttpServletSseServerTransportProvider with the
 		 * configured settings.
@@ -535,7 +600,8 @@ public HttpServletSseServerTransportProvider build() {
 			if (messageEndpoint == null) {
 				throw new IllegalStateException("MessageEndpoint must be set");
 			}
-			return new HttpServletSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint);
+			return new HttpServletSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
+					keepAliveInterval);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
index 4d2dc62f4..211a9c052 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
@@ -7,6 +7,7 @@
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.PrintWriter;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
@@ -28,12 +29,14 @@
 import io.modelcontextprotocol.spec.McpStreamableServerTransport;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.KeepAliveScheduler;
 import jakarta.servlet.AsyncContext;
 import jakarta.servlet.ServletException;
 import jakarta.servlet.annotation.WebServlet;
 import jakarta.servlet.http.HttpServlet;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
+import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
 /**
@@ -110,6 +113,12 @@ public class HttpServletStreamableServerTransportProvider extends HttpServlet
 	 */
 	private volatile boolean isClosing = false;
 
+	/**
+	 * Keep-alive scheduler for managing session pings. Activated if keepAliveInterval is
+	 * set. Disabled by default.
+	 */
+	private KeepAliveScheduler keepAliveScheduler;
+
 	/**
 	 * Constructs a new HttpServletStreamableServerTransportProvider instance.
 	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
@@ -121,7 +130,8 @@ public class HttpServletStreamableServerTransportProvider extends HttpServlet
 	 * @throws IllegalArgumentException if any parameter is null
 	 */
 	private HttpServletStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
-			boolean disallowDelete, McpTransportContextExtractor contextExtractor) {
+			boolean disallowDelete, McpTransportContextExtractor contextExtractor,
+			Duration keepAliveInterval) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
 		Assert.notNull(contextExtractor, "Context extractor must not be null");
@@ -130,6 +140,18 @@ private HttpServletStreamableServerTransportProvider(ObjectMapper objectMapper,
 		this.mcpEndpoint = mcpEndpoint;
 		this.disallowDelete = disallowDelete;
 		this.contextExtractor = contextExtractor;
+
+		if (keepAliveInterval != null) {
+
+			this.keepAliveScheduler = KeepAliveScheduler
+				.builder(() -> (isClosing) ? Flux.empty() : Flux.fromIterable(sessions.values()))
+				.initialDelay(keepAliveInterval)
+				.interval(keepAliveInterval)
+				.build();
+
+			this.keepAliveScheduler.start();
+		}
+
 	}
 
 	@Override
@@ -187,6 +209,12 @@ public Mono closeGracefully() {
 
 			this.sessions.clear();
 			logger.debug("Graceful shutdown completed");
+		}).then().doOnSuccess(v -> {
+			sessions.clear();
+			logger.debug("Graceful shutdown completed");
+			if (this.keepAliveScheduler != null) {
+				this.keepAliveScheduler.shutdown();
+			}
 		});
 	}
 
@@ -737,6 +765,8 @@ public static class Builder {
 
 		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
 
+		private Duration keepAliveInterval;
+
 		/**
 		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
@@ -784,6 +814,18 @@ public Builder contextExtractor(McpTransportContextExtractor
 			return this;
 		}
 
+		/**
+		 * Sets the keep-alive interval for the transport. If set, a keep-alive scheduler
+		 * will be activated to periodically ping active sessions.
+		 * @param keepAliveInterval The interval for keep-alive pings. If null, no
+		 * keep-alive will be scheduled.
+		 * @return this builder instance
+		 */
+		public Builder keepAliveInterval(Duration keepAliveInterval) {
+			this.keepAliveInterval = keepAliveInterval;
+			return this;
+		}
+
 		/**
 		 * Builds a new instance of {@link HttpServletStreamableServerTransportProvider}
 		 * with the configured settings.
@@ -795,7 +837,7 @@ public HttpServletStreamableServerTransportProvider build() {
 			Assert.notNull(this.mcpEndpoint, "MCP endpoint must be set");
 
 			return new HttpServletStreamableServerTransportProvider(this.objectMapper, this.mcpEndpoint,
-					this.disallowDelete, this.contextExtractor);
+					this.disallowDelete, this.contextExtractor, this.keepAliveInterval);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
index f600f28b3..c9b041fd6 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -1,26 +1,27 @@
 package io.modelcontextprotocol.spec;
 
+import java.time.Duration;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Supplier;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import com.fasterxml.jackson.core.type.TypeReference;
+
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
 import io.modelcontextprotocol.server.McpNotificationHandler;
 import io.modelcontextprotocol.server.McpRequestHandler;
 import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 import reactor.core.publisher.MonoSink;
 
-import java.time.Duration;
-import java.util.Map;
-import java.util.UUID;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.atomic.AtomicInteger;
-import java.util.concurrent.atomic.AtomicLong;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.Supplier;
-
 /**
  * Representation of a Streamable HTTP server session that keeps track of mapping
  * server-initiated requests to the client and mapping arriving responses. It also allows
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java b/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
new file mode 100644
index 000000000..30e8a2c2a
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
@@ -0,0 +1,216 @@
+/**
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+package io.modelcontextprotocol.util;
+
+import java.time.Duration;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.function.Supplier;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSession;
+import reactor.core.Disposable;
+import reactor.core.publisher.Flux;
+import reactor.core.scheduler.Scheduler;
+import reactor.core.scheduler.Schedulers;
+
+/**
+ * A utility class for scheduling regular keep-alive calls to maintain connections. It
+ * sends periodic keep-alive, ping, messages to connected mcp clients to prevent idle
+ * timeouts.
+ *
+ * The pings are sent to all active mcp sessions at regular intervals.
+ *
+ * @author Christian Tzolov
+ */
+public class KeepAliveScheduler {
+
+	private static final Logger logger = LoggerFactory.getLogger(KeepAliveScheduler.class);
+
+	private static final TypeReference OBJECT_TYPE_REF = new TypeReference<>() {
+	};
+
+	/** Initial delay before the first keepAlive call */
+	private final Duration initialDelay;
+
+	/** Interval between subsequent keepAlive calls */
+	private final Duration interval;
+
+	/** The scheduler used for executing keepAlive calls */
+	private final Scheduler scheduler;
+
+	/** The current state of the scheduler */
+	private final AtomicBoolean isRunning = new AtomicBoolean(false);
+
+	/** The current subscription for the keepAlive calls */
+	private Disposable currentSubscription;
+
+	// TODO Currently we do not support the streams (streamable http session created by
+	// http post/get)
+
+	/** Supplier for reactive McpSession instances */
+	private final Supplier> mcpSessions;
+
+	/**
+	 * Creates a KeepAliveScheduler with a custom scheduler, initial delay, interval and a
+	 * supplier for McpSession instances.
+	 * @param scheduler The scheduler to use for executing keepAlive calls
+	 * @param initialDelay Initial delay before the first keepAlive call
+	 * @param interval Interval between subsequent keepAlive calls
+	 * @param mcpSessions Supplier for McpSession instances
+	 */
+	KeepAliveScheduler(Scheduler scheduler, Duration initialDelay, Duration interval,
+			Supplier> mcpSessions) {
+		this.scheduler = scheduler;
+		this.initialDelay = initialDelay;
+		this.interval = interval;
+		this.mcpSessions = mcpSessions;
+	}
+
+	/**
+	 * Creates a new Builder instance for constructing KeepAliveScheduler.
+	 * @return A new Builder instance
+	 */
+	public static Builder builder(Supplier> mcpSessions) {
+		return new Builder(mcpSessions);
+	}
+
+	/**
+	 * Starts regular keepAlive calls with sessions supplier.
+	 * @return Disposable to control the scheduled execution
+	 */
+	public Disposable start() {
+		if (this.isRunning.compareAndSet(false, true)) {
+
+			this.currentSubscription = Flux.interval(this.initialDelay, this.interval, this.scheduler)
+				.doOnNext(tick -> {
+					this.mcpSessions.get()
+						.flatMap(session -> session.sendRequest(McpSchema.METHOD_PING, null, OBJECT_TYPE_REF)
+							.doOnError(e -> logger.warn("Failed to send keep-alive ping to session {}: {}", session,
+									e.getMessage()))
+							.onErrorComplete())
+						.subscribe();
+				})
+				.doOnCancel(() -> this.isRunning.set(false))
+				.doOnComplete(() -> this.isRunning.set(false))
+				.onErrorComplete(error -> {
+					logger.error("KeepAlive scheduler error", error);
+					this.isRunning.set(false);
+					return true;
+				})
+				.subscribe();
+
+			return this.currentSubscription;
+		}
+		else {
+			throw new IllegalStateException("KeepAlive scheduler is already running. Stop it first.");
+		}
+	}
+
+	/**
+	 * Stops the currently running keepAlive scheduler.
+	 */
+	public void stop() {
+		if (this.currentSubscription != null && !this.currentSubscription.isDisposed()) {
+			this.currentSubscription.dispose();
+		}
+		this.isRunning.set(false);
+	}
+
+	/**
+	 * Checks if the scheduler is currently running.
+	 * @return true if running, false otherwise
+	 */
+	public boolean isRunning() {
+		return this.isRunning.get();
+	}
+
+	/**
+	 * Shuts down the scheduler and releases resources.
+	 */
+	public void shutdown() {
+		stop();
+		if (this.scheduler instanceof Disposable) {
+			((Disposable) this.scheduler).dispose();
+		}
+	}
+
+	/**
+	 * Builder class for creating KeepAliveScheduler instances with fluent API.
+	 */
+	public static class Builder {
+
+		private Scheduler scheduler = Schedulers.boundedElastic();
+
+		private Duration initialDelay = Duration.ofSeconds(0);
+
+		private Duration interval = Duration.ofSeconds(30);
+
+		private Supplier> mcpSessions;
+
+		/**
+		 * Creates a new Builder instance with a supplier for McpSession instances.
+		 * @param mcpSessions The supplier for McpSession instances
+		 */
+		Builder(Supplier> mcpSessions) {
+			Assert.notNull(mcpSessions, "McpSessions supplier must not be null");
+			this.mcpSessions = mcpSessions;
+		}
+
+		/**
+		 * Sets the scheduler to use for executing keepAlive calls.
+		 * @param scheduler The scheduler to use:
+		 * 
    
+		 * 
  • Schedulers.single() - single-threaded scheduler
    • 
+		 * 
  • Schedulers.boundedElastic() - bounded elastic scheduler for I/O operations
+		 * (Default)
    • 
+		 * 
  • Schedulers.parallel() - parallel scheduler for CPU-intensive
+		 * operations
    • 
+		 * 
  • Schedulers.immediate() - immediate scheduler for synchronous execution
    • 
+		 * 

+		 * @return This builder instance for method chaining
+		 */
+		public Builder scheduler(Scheduler scheduler) {
+			Assert.notNull(scheduler, "Scheduler must not be null");
+			this.scheduler = scheduler;
+			return this;
+		}
+
+		/**
+		 * Sets the initial delay before the first keepAlive call.
+		 * @param initialDelay The initial delay duration
+		 * @return This builder instance for method chaining
+		 */
+		public Builder initialDelay(Duration initialDelay) {
+			Assert.notNull(initialDelay, "Initial delay must not be null");
+			this.initialDelay = initialDelay;
+			return this;
+		}
+
+		/**
+		 * Sets the interval between subsequent keepAlive calls.
+		 * @param interval The interval duration
+		 * @return This builder instance for method chaining
+		 */
+		public Builder interval(Duration interval) {
+			Assert.notNull(interval, "Interval must not be null");
+			this.interval = interval;
+			return this;
+		}
+
+		/**
+		 * Builds and returns a new KeepAliveScheduler instance.
+		 * @return A new KeepAliveScheduler configured with the builder's settings
+		 */
+		public KeepAliveScheduler build() {
+			return new KeepAliveScheduler(scheduler, initialDelay, interval, mcpSessions);
+		}
+
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 3377f98a6..ecb0c33c3 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -38,6 +38,7 @@ public void before() {
 		mcpServerTransportProvider = HttpServletStreamableServerTransportProvider.builder()
 			.objectMapper(new ObjectMapper())
 			.mcpEndpoint(MESSAGE_ENDPOINT)
+			.keepAliveInterval(Duration.ofSeconds(1))
 			.build();
 
 		tomcat = TomcatTestUtil.createTomcatServer("", PORT, mcpServerTransportProvider);
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java b/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
new file mode 100644
index 000000000..4de9363c2
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
@@ -0,0 +1,303 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.util;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+
+import java.time.Duration;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Supplier;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSession;
+import reactor.core.Disposable;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import reactor.test.scheduler.VirtualTimeScheduler;
+
+/**
+ * Unit tests for {@link KeepAliveScheduler}.
+ *
+ * @author Christian Tzolov
+ */
+class KeepAliveSchedulerTests {
+
+	private MockMcpSession mockSession1;
+
+	private MockMcpSession mockSession2;
+
+	private Supplier> mockSessionsSupplier;
+
+	private VirtualTimeScheduler virtualTimeScheduler;
+
+	@BeforeEach
+	void setUp() {
+		virtualTimeScheduler = VirtualTimeScheduler.create();
+		mockSession1 = new MockMcpSession();
+		mockSession2 = new MockMcpSession();
+		mockSessionsSupplier = () -> Flux.just(mockSession1);
+	}
+
+	@AfterEach
+	void tearDown() {
+		if (virtualTimeScheduler != null) {
+			virtualTimeScheduler.dispose();
+		}
+	}
+
+	@Test
+	void testBuilderWithNullSessionsSupplier() {
+		assertThatThrownBy(() -> KeepAliveScheduler.builder(null)).isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("McpSessions supplier must not be null");
+	}
+
+	@Test
+	void testBuilderWithNullScheduler() {
+		assertThatThrownBy(() -> KeepAliveScheduler.builder(mockSessionsSupplier).scheduler(null))
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Scheduler must not be null");
+	}
+
+	@Test
+	void testBuilderWithNullInitialDelay() {
+		assertThatThrownBy(() -> KeepAliveScheduler.builder(mockSessionsSupplier).initialDelay(null))
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Initial delay must not be null");
+	}
+
+	@Test
+	void testBuilderWithNullInterval() {
+		assertThatThrownBy(() -> KeepAliveScheduler.builder(mockSessionsSupplier).interval(null))
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Interval must not be null");
+	}
+
+	@Test
+	void testBuilderDefaults() {
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier).build();
+
+		assertThat(scheduler).isNotNull();
+		assertThat(scheduler.isRunning()).isFalse();
+	}
+
+	@Test
+	void testStartWithMultipleSessions() {
+		mockSessionsSupplier = () -> Flux.just(mockSession1, mockSession2);
+
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier)
+			.scheduler(virtualTimeScheduler)
+			.initialDelay(Duration.ofSeconds(1))
+			.interval(Duration.ofSeconds(2))
+			.build();
+
+		assertThat(scheduler.isRunning()).isFalse();
+
+		// Start the scheduler
+		Disposable disposable = scheduler.start();
+
+		assertThat(scheduler.isRunning()).isTrue();
+		assertThat(disposable).isNotNull();
+		assertThat(disposable.isDisposed()).isFalse();
+
+		// Advance time to trigger the first ping
+		virtualTimeScheduler.advanceTimeBy(Duration.ofSeconds(1));
+
+		// Verify both sessions received ping
+		assertThat(mockSession1.getPingCount()).isEqualTo(1);
+		assertThat(mockSession2.getPingCount()).isEqualTo(1);
+
+		virtualTimeScheduler.advanceTimeBy(Duration.ofSeconds(2)); // Second ping
+		virtualTimeScheduler.advanceTimeBy(Duration.ofSeconds(2)); // Third ping
+		virtualTimeScheduler.advanceTimeBy(Duration.ofSeconds(2)); // Fourth ping
+
+		// Verify second ping was sent
+		assertThat(mockSession1.getPingCount()).isEqualTo(4);
+		assertThat(mockSession2.getPingCount()).isEqualTo(4);
+
+		// Clean up
+		scheduler.stop();
+
+		assertThat(scheduler.isRunning()).isFalse();
+		assertThat(disposable).isNotNull();
+		assertThat(disposable.isDisposed()).isTrue();
+	}
+
+	@Test
+	void testStartWithEmptySessionsList() {
+		mockSessionsSupplier = () -> Flux.empty();
+
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier)
+			.scheduler(virtualTimeScheduler)
+			.initialDelay(Duration.ofSeconds(1))
+			.interval(Duration.ofSeconds(2))
+			.build();
+
+		// Start the scheduler
+		scheduler.start();
+
+		// Advance time to trigger ping attempts
+		virtualTimeScheduler.advanceTimeBy(Duration.ofSeconds(1));
+
+		// Verify no sessions were called (since list was empty)
+		assertThat(mockSession1.getPingCount()).isEqualTo(0);
+		assertThat(mockSession2.getPingCount()).isEqualTo(0);
+
+		// Clean up
+		scheduler.stop();
+	}
+
+	@Test
+	void testStartWhenAlreadyRunning() {
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier)
+			.scheduler(virtualTimeScheduler)
+			.build();
+
+		// Start the scheduler
+		scheduler.start();
+
+		// Try to start again - should throw exception
+		assertThatThrownBy(scheduler::start).isInstanceOf(IllegalStateException.class)
+			.hasMessage("KeepAlive scheduler is already running. Stop it first.");
+
+		// Clean up
+		scheduler.stop();
+	}
+
+	@Test
+	void testStopWhenNotRunning() {
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier)
+			.scheduler(virtualTimeScheduler)
+			.build();
+
+		// Should not throw exception when stopping a non-running scheduler
+		assertDoesNotThrow(scheduler::stop);
+		assertThat(scheduler.isRunning()).isFalse();
+	}
+
+	@Test
+	void testShutdown() {
+		// Setup with a separate virtual time scheduler (which is disposable)
+		VirtualTimeScheduler separateScheduler = VirtualTimeScheduler.create();
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier)
+			.scheduler(separateScheduler)
+			.build();
+
+		// Start the scheduler
+		scheduler.start();
+		assertThat(scheduler.isRunning()).isTrue();
+
+		// Shutdown should stop the scheduler and dispose the scheduler
+		scheduler.shutdown();
+		assertThat(scheduler.isRunning()).isFalse();
+		assertThat(separateScheduler.isDisposed()).isTrue();
+	}
+
+	@Test
+	void testPingFailureHandling() {
+		// Setup session that fails ping
+		mockSession1.setShouldFailPing(true);
+
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier)
+			.scheduler(virtualTimeScheduler)
+			.initialDelay(Duration.ofSeconds(1))
+			.interval(Duration.ofSeconds(2))
+			.build();
+
+		// Start the scheduler
+		scheduler.start();
+
+		// Advance time to trigger the ping
+		virtualTimeScheduler.advanceTimeBy(Duration.ofSeconds(1));
+
+		// Verify ping was attempted (error should be handled gracefully)
+		assertThat(mockSession1.getPingCount()).isEqualTo(1);
+
+		// Scheduler should still be running despite the error
+		assertThat(scheduler.isRunning()).isTrue();
+
+		// Clean up
+		scheduler.stop();
+	}
+
+	@Test
+	void testDisposableReturnedFromStart() {
+		KeepAliveScheduler scheduler = KeepAliveScheduler.builder(mockSessionsSupplier)
+			.scheduler(virtualTimeScheduler)
+			.build();
+
+		// Start and get disposable
+		Disposable disposable = scheduler.start();
+
+		assertThat(disposable).isNotNull();
+		assertThat(disposable.isDisposed()).isFalse();
+		assertThat(scheduler.isRunning()).isTrue();
+
+		// Dispose directly through the returned disposable
+		disposable.dispose();
+
+		assertThat(disposable.isDisposed()).isTrue();
+		assertThat(scheduler.isRunning()).isFalse();
+	}
+
+	/**
+	 * Simple mock implementation of McpSession for testing purposes.
+	 */
+	private static class MockMcpSession implements McpSession {
+
+		private final AtomicInteger pingCount = new AtomicInteger(0);
+
+		private boolean shouldFailPing = false;
+
+		@Override
+		public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+			if (McpSchema.METHOD_PING.equals(method)) {
+				pingCount.incrementAndGet();
+				if (shouldFailPing) {
+					return Mono.error(new RuntimeException("Connection failed"));
+				}
+				return Mono.just((T) new Object());
+			}
+			return Mono.empty();
+		}
+
+		@Override
+		public Mono sendNotification(String method, Object params) {
+			return Mono.empty();
+		}
+
+		@Override
+		public Mono closeGracefully() {
+			return Mono.empty();
+		}
+
+		@Override
+		public void close() {
+			// No-op for mock
+		}
+
+		public int getPingCount() {
+			return pingCount.get();
+		}
+
+		public void setShouldFailPing(boolean shouldFailPing) {
+			this.shouldFailPing = shouldFailPing;
+		}
+
+		@Override
+		public String toString() {
+			return "MockMcpSession";
+		}
+
+	}
+
+}

From 67de84b300731e55c1c2e014138bce4c384ab0b5 Mon Sep 17 00:00:00 2001
From: Ilayaperumal Gopinathan 
Date: Fri, 25 Jul 2025 19:06:02 +0100
Subject: [PATCH 024/125] Expose the client initialization result

 - Add getters for both MCP Sync/Async clients

Signed-off-by: Ilayaperumal Gopinathan 
---
 .../io/modelcontextprotocol/client/McpAsyncClient.java    | 8 ++++++++
 .../io/modelcontextprotocol/client/McpSyncClient.java     | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 405e7123f..22c0ee1d2 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -278,6 +278,14 @@ public class McpAsyncClient {
 		this.transport.setExceptionHandler(this.initializer::handleException);
 	}
 
+	/**
+	 * Get the current initialization result.
+	 * @return the initialization result.
+	 */
+	public McpSchema.InitializeResult getCurrentInitializationResult() {
+		return this.initializer.currentInitializationResult();
+	}
+
 	/**
 	 * Get the server capabilities that define the supported features and functionality.
 	 * @return The server capabilities
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
index 83c4900d1..33784adcd 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
@@ -73,6 +73,14 @@ public class McpSyncClient implements AutoCloseable {
 		this.delegate = delegate;
 	}
 
+	/**
+	 * Get the current initialization result.
+	 * @return the initialization result.
+	 */
+	public McpSchema.InitializeResult getCurrentInitializationResult() {
+		return this.delegate.getCurrentInitializationResult();
+	}
+
 	/**
 	 * Get the server capabilities that define the supported features and functionality.
 	 * @return The server capabilities

From 9d586219183faf0fd0edc33f99ec946bfe66e923 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Wed, 30 Jul 2025 23:54:28 +0200
Subject: [PATCH 025/125] feat: implement MCP protocol version per transport
 support (#404)

- Add protocolVersion() method to transport and transport provider interfaces and implementations
- Replace hardcoded HTTP header strings with HttpHeaders constants
- Update protocol versions to be transport-specific rather than global
- Deprecate McpSchema.LATEST_PROTOCOL_VERSION in favor of transport-specific versions
- Standardize header names: MCP-Protocol-Version, mcp-session-id, last-event-id
- Update clients and servers to use transport.protocolVersion() for initialization
- Refactor tests to use transport-specific protocol versions
- Include MCP-Protocol-Version header in all GET/POST/DELETE requests
- Update WebClientStreamableHttpTransport, WebFluxSseClientTransport,
  HttpClientSseClientTransport, and HttpClientStreamableHttpTransport

Related to #398 , #363 , #250

Signed-off-by: Christian Tzolov 
---
 .../WebClientStreamableHttpTransport.java     | 38 ++++++++++++++-----
 .../transport/WebFluxSseClientTransport.java  | 11 ++++++
 .../WebFluxSseServerTransportProvider.java    |  7 ++++
 .../WebFluxStatelessServerTransport.java      |  1 -
 ...FluxStreamableServerTransportProvider.java |  5 +++
 .../WebMvcSseServerTransportProvider.java     |  5 +++
 ...bMvcStreamableServerTransportProvider.java |  5 +++
 .../WebMvcSseCustomContextPathTests.java      | 11 +++++-
 .../client/McpAsyncClient.java                |  5 +--
 .../HttpClientSseClientTransport.java         | 15 +++++++-
 .../HttpClientStreamableHttpTransport.java    | 22 +++++++++--
 .../server/McpAsyncServer.java                |  6 ++-
 .../server/McpStatelessAsyncServer.java       |  4 +-
 ...HttpServletSseServerTransportProvider.java |  5 +++
 ...vletStreamableServerTransportProvider.java |  5 +++
 .../StdioServerTransportProvider.java         |  5 +++
 .../spec/HttpHeaders.java                     |  5 +++
 .../modelcontextprotocol/spec/McpSchema.java  |  1 +
 .../spec/McpServerTransportProviderBase.java  |  8 ++++
 .../spec/McpStatelessServerTransport.java     |  4 ++
 .../McpStreamableServerTransportProvider.java |  2 -
 .../spec/McpTransport.java                    |  4 ++
 .../MockMcpClientTransport.java               | 11 ++++++
 .../McpAsyncClientResponseHandlerTests.java   |  4 +-
 .../client/McpAsyncClientTests.java           |  4 +-
 .../client/McpClientProtocolVersionTests.java |  6 +--
 .../server/McpServerProtocolVersionTests.java |  4 +-
 27 files changed, 169 insertions(+), 34 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 6fa76cc2e..d7f7f9bfb 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -23,6 +23,7 @@
 
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
+import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -66,6 +67,8 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(WebClientStreamableHttpTransport.class);
 
+	private static final String MCP_PROTOCOL_VERSION = "2025-03-26";
+
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
 	/**
@@ -103,6 +106,11 @@ private WebClientStreamableHttpTransport(ObjectMapper objectMapper, WebClient.Bu
 		this.activeSession.set(createTransportSession());
 	}
 
+	@Override
+	public String protocolVersion() {
+		return MCP_PROTOCOL_VERSION;
+	}
+
 	/**
 	 * Create a stateful builder for creating {@link WebClientStreamableHttpTransport}
 	 * instances.
@@ -128,12 +136,20 @@ public Mono connect(Function, Mono> onClose = sessionId -> sessionId == null ? Mono.empty()
-				: webClient.delete().uri(this.endpoint).headers(httpHeaders -> {
-					httpHeaders.add("mcp-session-id", sessionId);
-				}).retrieve().toBodilessEntity().onErrorComplete(e -> {
-					logger.warn("Got error when closing transport", e);
-					return true;
-				}).then();
+				: webClient.delete()
+					.uri(this.endpoint)
+					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
+					.headers(httpHeaders -> {
+						httpHeaders.add(HttpHeaders.MCP_SESSION_ID, sessionId);
+						httpHeaders.add(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION);
+					})
+					.retrieve()
+					.toBodilessEntity()
+					.onErrorComplete(e -> {
+						logger.warn("Got error when closing transport", e);
+						return true;
+					})
+					.then();
 		return new DefaultMcpTransportSession(onClose);
 	}
 
@@ -186,10 +202,11 @@ private Mono reconnect(McpTransportStream stream) {
 			Disposable connection = webClient.get()
 				.uri(this.endpoint)
 				.accept(MediaType.TEXT_EVENT_STREAM)
+				.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 				.headers(httpHeaders -> {
-					transportSession.sessionId().ifPresent(id -> httpHeaders.add("mcp-session-id", id));
+					transportSession.sessionId().ifPresent(id -> httpHeaders.add(HttpHeaders.MCP_SESSION_ID, id));
 					if (stream != null) {
-						stream.lastId().ifPresent(id -> httpHeaders.add("last-event-id", id));
+						stream.lastId().ifPresent(id -> httpHeaders.add(HttpHeaders.LAST_EVENT_ID, id));
 					}
 				})
 				.exchangeToFlux(response -> {
@@ -246,13 +263,14 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			Disposable connection = webClient.post()
 				.uri(this.endpoint)
 				.accept(MediaType.APPLICATION_JSON, MediaType.TEXT_EVENT_STREAM)
+				.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 				.headers(httpHeaders -> {
-					transportSession.sessionId().ifPresent(id -> httpHeaders.add("mcp-session-id", id));
+					transportSession.sessionId().ifPresent(id -> httpHeaders.add(HttpHeaders.MCP_SESSION_ID, id));
 				})
 				.bodyValue(message)
 				.exchangeToFlux(response -> {
 					if (transportSession
-						.markInitialized(response.headers().asHttpHeaders().getFirst("mcp-session-id"))) {
+						.markInitialized(response.headers().asHttpHeaders().getFirst(HttpHeaders.MCP_SESSION_ID))) {
 						// Once we have a session, we try to open an async stream for
 						// the server to send notifications and requests out-of-band.
 						reconnect(null).contextWrite(sink.contextView()).subscribe();
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
index 59385b54a..fe6b07a6d 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
@@ -9,6 +9,8 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -62,6 +64,8 @@ public class WebFluxSseClientTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(WebFluxSseClientTransport.class);
 
+	private static final String MCP_PROTOCOL_VERSION = "2024-11-05";
+
 	/**
 	 * Event type for JSON-RPC messages received through the SSE connection. The server
 	 * sends messages with this event type to transmit JSON-RPC protocol data.
@@ -166,6 +170,11 @@ public WebFluxSseClientTransport(WebClient.Builder webClientBuilder, ObjectMappe
 		this.sseEndpoint = sseEndpoint;
 	}
 
+	@Override
+	public String protocolVersion() {
+		return MCP_PROTOCOL_VERSION;
+	}
+
 	/**
 	 * Establishes a connection to the MCP server using Server-Sent Events (SSE). This
 	 * method initiates the SSE connection and sets up the message processing pipeline.
@@ -250,6 +259,7 @@ public Mono sendMessage(JSONRPCMessage message) {
 				return webClient.post()
 					.uri(messageEndpointUri)
 					.contentType(MediaType.APPLICATION_JSON)
+					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.bodyValue(jsonText)
 					.retrieve()
 					.toBodilessEntity()
@@ -282,6 +292,7 @@ protected Flux> eventStream() {// @formatter:off
 			.get()
 			.uri(this.sseEndpoint)
 			.accept(MediaType.TEXT_EVENT_STREAM)
+			.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 			.retrieve()
 			.bodyToFlux(SSE_TYPE)
 			.retryWhen(Retry.from(retrySignal -> retrySignal.handle(inboundRetryHandler)));
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index b1b5246c8..67810fb56 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -79,6 +79,8 @@ public class WebFluxSseServerTransportProvider implements McpServerTransportProv
 	 */
 	public static final String ENDPOINT_EVENT_TYPE = "endpoint";
 
+	private static final String MCP_PROTOCOL_VERSION = "2025-06-18";
+
 	/**
 	 * Default SSE endpoint path as specified by the MCP transport specification.
 	 */
@@ -212,6 +214,11 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseU
 		}
 	}
 
+	@Override
+	public String protocolVersion() {
+		return "2024-11-05";
+	}
+
 	@Override
 	public void setSessionFactory(McpServerSession.Factory sessionFactory) {
 		this.sessionFactory = sessionFactory;
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
index e75e9262d..c514f2dff 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
@@ -21,7 +21,6 @@
 
 import java.io.IOException;
 import java.util.List;
-import java.util.function.Function;
 
 /**
  * Implementation of a WebFlux based {@link McpStatelessServerTransport}.
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index 79224a57d..00ec68c5d 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -95,6 +95,11 @@ private WebFluxStreamableServerTransportProvider(ObjectMapper objectMapper, Stri
 
 	}
 
+	@Override
+	public String protocolVersion() {
+		return "2025-03-26";
+	}
+
 	@Override
 	public void setSessionFactory(McpStreamableServerSession.Factory sessionFactory) {
 		this.sessionFactory = sessionFactory;
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index b90f9fb3d..a3898006d 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -209,6 +209,11 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUr
 		}
 	}
 
+	@Override
+	public String protocolVersion() {
+		return "2024-11-05";
+	}
+
 	@Override
 	public void setSessionFactory(McpServerSession.Factory sessionFactory) {
 		this.sessionFactory = sessionFactory;
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index 391aa3e8d..2f94d5c11 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -147,6 +147,11 @@ private WebMvcStreamableServerTransportProvider(ObjectMapper objectMapper, Strin
 		}
 	}
 
+	@Override
+	public String protocolVersion() {
+		return "2025-03-26";
+	}
+
 	@Override
 	public void setSessionFactory(McpStreamableServerSession.Factory sessionFactory) {
 		this.sessionFactory = sessionFactory;
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java
index 1b5218cc5..cce36d191 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java
@@ -91,8 +91,15 @@ static class TestConfig {
 		@Bean
 		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
 
-			return new WebMvcSseServerTransportProvider(new ObjectMapper(), CUSTOM_CONTEXT_PATH, MESSAGE_ENDPOINT,
-					WebMvcSseServerTransportProvider.DEFAULT_SSE_ENDPOINT);
+			return WebMvcSseServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.baseUrl(CUSTOM_CONTEXT_PATH)
+				.messageEndpoint(MESSAGE_ENDPOINT)
+				.sseEndpoint(WebMvcSseServerTransportProvider.DEFAULT_SSE_ENDPOINT)
+				.build();
+			// return new WebMvcSseServerTransportProvider(new ObjectMapper(),
+			// CUSTOM_CONTEXT_PATH, MESSAGE_ENDPOINT,
+			// WebMvcSseServerTransportProvider.DEFAULT_SSE_ENDPOINT);
 		}
 
 		@Bean
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 22c0ee1d2..73765122f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -272,9 +272,8 @@ public class McpAsyncClient {
 				asyncProgressNotificationHandler(progressConsumersFinal));
 
 		this.initializer = new LifecycleInitializer(clientCapabilities, clientInfo,
-				List.of(McpSchema.LATEST_PROTOCOL_VERSION), initializationTimeout,
-				ctx -> new McpClientSession(requestTimeout, transport, requestHandlers, notificationHandlers,
-						con -> con.contextWrite(ctx)));
+				List.of(transport.protocolVersion()), initializationTimeout, ctx -> new McpClientSession(requestTimeout,
+						transport, requestHandlers, notificationHandlers, con -> con.contextWrite(ctx)));
 		this.transport.setExceptionHandler(this.initializer::handleException);
 	}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 39fb0d461..3fe88fec8 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -61,6 +61,10 @@
  */
 public class HttpClientSseClientTransport implements McpClientTransport {
 
+	private static final String MCP_PROTOCOL_VERSION = "2024-11-05";
+
+	private static final String MCP_PROTOCOL_VERSION_HEADER_NAME = "MCP-Protocol-Version";
+
 	private static final Logger logger = LoggerFactory.getLogger(HttpClientSseClientTransport.class);
 
 	/** SSE event type for JSON-RPC messages */
@@ -211,6 +215,11 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 		this.httpRequestCustomizer = httpRequestCustomizer;
 	}
 
+	@Override
+	public String protocolVersion() {
+		return MCP_PROTOCOL_VERSION;
+	}
+
 	/**
 	 * Creates a new builder for {@link HttpClientSseClientTransport}.
 	 * @param baseUri the base URI of the MCP server
@@ -391,6 +400,7 @@ public Mono connect(Function, Mono> h
 				.uri(uri)
 				.header("Accept", "text/event-stream")
 				.header("Cache-Control", "no-cache")
+				.header(MCP_PROTOCOL_VERSION_HEADER_NAME, MCP_PROTOCOL_VERSION)
 				.GET();
 			return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null));
 		}).flatMap(requestBuilder -> Mono.create(sink -> {
@@ -516,7 +526,10 @@ private Mono serializeMessage(final JSONRPCMessage message) {
 	private Mono> sendHttpPost(final String endpoint, final String body) {
 		final URI requestUri = Utils.resolveUri(baseUri, endpoint);
 		return Mono.defer(() -> {
-			var builder = this.requestBuilder.copy().uri(requestUri).POST(HttpRequest.BodyPublishers.ofString(body));
+			var builder = this.requestBuilder.copy()
+				.uri(requestUri)
+				.header(MCP_PROTOCOL_VERSION_HEADER_NAME, MCP_PROTOCOL_VERSION)
+				.POST(HttpRequest.BodyPublishers.ofString(body));
 			return Mono.from(this.httpRequestCustomizer.customize(builder, "POST", requestUri, body));
 		}).flatMap(customizedBuilder -> {
 			var request = customizedBuilder.build();
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index 799716584..dadb09abc 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -28,6 +28,7 @@
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
+import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -72,6 +73,8 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(HttpClientStreamableHttpTransport.class);
 
+	private static final String MCP_PROTOCOL_VERSION = "2025-03-26";
+
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
 	/**
@@ -131,6 +134,11 @@ private HttpClientStreamableHttpTransport(ObjectMapper objectMapper, HttpClient
 		this.httpRequestCustomizer = httpRequestCustomizer;
 	}
 
+	@Override
+	public String protocolVersion() {
+		return MCP_PROTOCOL_VERSION;
+	}
+
 	public static Builder builder(String baseUri) {
 		return new Builder(baseUri);
 	}
@@ -157,12 +165,14 @@ private DefaultMcpTransportSession createTransportSession() {
 	}
 
 	private Publisher createDelete(String sessionId) {
+
 		var uri = Utils.resolveUri(this.baseUri, this.endpoint);
 		return Mono.defer(() -> {
 			var builder = this.requestBuilder.copy()
 				.uri(uri)
 				.header("Cache-Control", "no-cache")
-				.header("mcp-session-id", sessionId)
+				.header(HttpHeaders.MCP_SESSION_ID, sessionId)
+				.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 				.DELETE();
 			return Mono.from(this.httpRequestCustomizer.customize(builder, "DELETE", uri, null));
 		}).flatMap(requestBuilder -> {
@@ -221,16 +231,18 @@ private Mono reconnect(McpTransportStream stream) {
 				HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
 
 				if (transportSession != null && transportSession.sessionId().isPresent()) {
-					requestBuilder = requestBuilder.header("mcp-session-id", transportSession.sessionId().get());
+					requestBuilder = requestBuilder.header(HttpHeaders.MCP_SESSION_ID,
+							transportSession.sessionId().get());
 				}
 
 				if (stream != null && stream.lastId().isPresent()) {
-					requestBuilder = requestBuilder.header("last-event-id", stream.lastId().get());
+					requestBuilder = requestBuilder.header(HttpHeaders.LAST_EVENT_ID, stream.lastId().get());
 				}
 
 				var builder = requestBuilder.uri(uri)
 					.header("Accept", TEXT_EVENT_STREAM)
 					.header("Cache-Control", "no-cache")
+					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.GET();
 				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null));
 			})
@@ -377,13 +389,15 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 				HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
 
 				if (transportSession != null && transportSession.sessionId().isPresent()) {
-					requestBuilder = requestBuilder.header("mcp-session-id", transportSession.sessionId().get());
+					requestBuilder = requestBuilder.header(HttpHeaders.MCP_SESSION_ID,
+							transportSession.sessionId().get());
 				}
 
 				var builder = requestBuilder.uri(uri)
 					.header("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
 					.header("Content-Type", APPLICATION_JSON)
 					.header("Cache-Control", "no-cache")
+					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
 				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, jsonBody));
 			}).flatMapMany(requestBuilder -> Flux.create(responseEventSink -> {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index 1b3eee3c8..9605fb3f2 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -115,7 +115,7 @@ public class McpAsyncServer {
 
 	private final ConcurrentHashMap completions = new ConcurrentHashMap<>();
 
-	private List protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
+	private List protocolVersions;
 
 	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
@@ -145,6 +145,8 @@ public class McpAsyncServer {
 		Map> requestHandlers = prepareRequestHandlers();
 		Map notificationHandlers = prepareNotificationHandlers(features);
 
+		this.protocolVersions = List.of(mcpTransportProvider.protocolVersion());
+
 		mcpTransportProvider.setSessionFactory(transport -> new McpServerSession(UUID.randomUUID().toString(),
 				requestTimeout, transport, this::asyncInitializeRequestHandler, requestHandlers, notificationHandlers));
 	}
@@ -168,6 +170,8 @@ public class McpAsyncServer {
 		Map> requestHandlers = prepareRequestHandlers();
 		Map notificationHandlers = prepareNotificationHandlers(features);
 
+		this.protocolVersions = List.of(mcpTransportProvider.protocolVersion());
+
 		mcpTransportProvider.setSessionFactory(new DefaultMcpStreamableServerSessionFactory(requestTimeout,
 				this::asyncInitializeRequestHandler, requestHandlers, notificationHandlers));
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 63fefa31d..565c53f13 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -63,7 +63,7 @@ public class McpStatelessAsyncServer {
 
 	private final ConcurrentHashMap completions = new ConcurrentHashMap<>();
 
-	private List protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
+	private List protocolVersions;
 
 	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
@@ -118,6 +118,8 @@ public class McpStatelessAsyncServer {
 			requestHandlers.put(McpSchema.METHOD_COMPLETION_COMPLETE, completionCompleteRequestHandler());
 		}
 
+		this.protocolVersions = List.of(mcpTransport.protocolVersion());
+
 		McpStatelessServerHandler handler = new DefaultMcpStatelessServerHandler(requestHandlers, Map.of());
 		mcpTransport.setMcpHandler(handler);
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index 5c0b85f26..24e749fc3 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -178,6 +178,11 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String b
 		}
 	}
 
+	@Override
+	public String protocolVersion() {
+		return "2024-11-05";
+	}
+
 	/**
 	 * Creates a new HttpServletSseServerTransportProvider instance with the default SSE
 	 * endpoint.
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
index 211a9c052..6805bf194 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
@@ -154,6 +154,11 @@ private HttpServletStreamableServerTransportProvider(ObjectMapper objectMapper,
 
 	}
 
+	@Override
+	public String protocolVersion() {
+		return "2025-03-26";
+	}
+
 	@Override
 	public void setSessionFactory(McpStreamableServerSession.Factory sessionFactory) {
 		this.sessionFactory = sessionFactory;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
index 9ef9c7829..d2943b31d 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
@@ -88,6 +88,11 @@ public StdioServerTransportProvider(ObjectMapper objectMapper, InputStream input
 		this.outputStream = outputStream;
 	}
 
+	@Override
+	public String protocolVersion() {
+		return "2024-11-05";
+	}
+
 	@Override
 	public void setSessionFactory(McpServerSession.Factory sessionFactory) {
 		// Create a single session for the stdio connection
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
index 2e8084915..c1c4c7a7d 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
@@ -17,4 +17,9 @@ public interface HttpHeaders {
 	 */
 	String LAST_EVENT_ID = "last-event-id";
 
+	/**
+	 * Identifies the MCP protocol version.
+	 */
+	String PROTOCOL_VERSION = "MCP-Protocol-Version";
+
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index a3812dbc2..fb4baabfb 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -44,6 +44,7 @@ public final class McpSchema {
 	private McpSchema() {
 	}
 
+	@Deprecated
 	public static final String LATEST_PROTOCOL_VERSION = "2025-03-26";
 
 	public static final String JSONRPC_VERSION = "2.0";
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
index 87e7d6441..798575017 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
@@ -55,4 +55,12 @@ default void close() {
 	 */
 	Mono closeGracefully();
 
+	/**
+	 * Returns the protocol version supported by this transport provider.
+	 * @return the protocol version as a string
+	 */
+	default String protocolVersion() {
+		return "2024-11-05";
+	}
+
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
index b6211fe3b..329908469 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
@@ -22,4 +22,8 @@ default void close() {
 	 */
 	Mono closeGracefully();
 
+	default String protocolVersion() {
+		return "2025-03-26";
+	}
+
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
index 87574e8ab..b75081096 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
@@ -2,8 +2,6 @@
 
 import reactor.core.publisher.Mono;
 
-import java.util.Map;
-
 /**
  * The core building block providing the server-side MCP transport for Streamable HTTP
  * servers. Implement this interface to bridge between a particular server-side technology
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
index 40d9ba7ac..49c485059 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
@@ -77,4 +77,8 @@ default void close() {
 	 */
 	 T unmarshalFrom(Object data, TypeReference typeRef);
 
+	default String protocolVersion() {
+		return "2024-11-05";
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java b/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
index 482d0aac6..b531d5739 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
@@ -29,6 +29,8 @@ public class MockMcpClientTransport implements McpClientTransport {
 
 	private final BiConsumer interceptor;
 
+	private String protocolVersion = McpSchema.LATEST_PROTOCOL_VERSION;
+
 	public MockMcpClientTransport() {
 		this((t, msg) -> {
 		});
@@ -38,6 +40,15 @@ public MockMcpClientTransport(BiConsumer {
-				assertThat(result.protocolVersion()).isEqualTo(McpSchema.LATEST_PROTOCOL_VERSION);
+				assertThat(result.protocolVersion()).isEqualTo(transport.protocolVersion());
 			}).verifyComplete();
 
 		}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
index f643f1ba3..95086ee81 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
@@ -45,7 +45,7 @@ void shouldUseLatestVersionByDefault() {
 		assertThat(jsonResponse.id()).isEqualTo(requestId);
 		assertThat(jsonResponse.result()).isInstanceOf(McpSchema.InitializeResult.class);
 		McpSchema.InitializeResult result = (McpSchema.InitializeResult) jsonResponse.result();
-		assertThat(result.protocolVersion()).isEqualTo(McpSchema.LATEST_PROTOCOL_VERSION);
+		assertThat(result.protocolVersion()).isEqualTo(transportProvider.protocolVersion());
 
 		server.closeGracefully().subscribe();
 	}
@@ -93,7 +93,7 @@ void shouldSuggestLatestVersionForUnsupportedVersion() {
 		assertThat(jsonResponse.id()).isEqualTo(requestId);
 		assertThat(jsonResponse.result()).isInstanceOf(McpSchema.InitializeResult.class);
 		McpSchema.InitializeResult result = (McpSchema.InitializeResult) jsonResponse.result();
-		assertThat(result.protocolVersion()).isEqualTo(McpSchema.LATEST_PROTOCOL_VERSION);
+		assertThat(result.protocolVersion()).isEqualTo(transportProvider.protocolVersion());
 
 		server.closeGracefully().subscribe();
 	}

From 8f03a40540befef877db592930e6c7f2df3c0ee3 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Wed, 30 Jul 2025 23:47:44 +0200
Subject: [PATCH 026/125] feat: add WebMVC and HttpServlet stateless server
 transports

- Add WebMvcStatelessServerTransport for mcp-spring-webmvc module
- Add HttpServletStatelessServerTransport for mcp module
- Implement builder patterns for AsyncToolSpecification and SyncToolSpecification
- Create AbstractStatelessIntegrationTests base class for shared test functionality
- Add integration tests for both transport implementations

Signed-off-by: Christian Tzolov 
---
 .../WebMvcStatelessServerTransport.java       | 237 ++++++++
 .../WebMvcStatelessIntegrationTests.java      | 165 ++++++
 .../AbstractStatelessIntegrationTests.java    | 538 ++++++++++++++++++
 .../server/McpStatelessServerFeatures.java    | 103 ++++
 .../HttpServletStatelessServerTransport.java  | 306 ++++++++++
 .../HttpServletStatelessIntegrationTests.java | 473 +++++++++++++++
 6 files changed, 1822 insertions(+)
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
 create mode 100644 mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java

diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
new file mode 100644
index 000000000..1b026fc46
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
@@ -0,0 +1,237 @@
+package io.modelcontextprotocol.server.transport;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.McpStatelessServerHandler;
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpStatelessServerTransport;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.util.Assert;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.RouterFunctions;
+import org.springframework.web.servlet.function.ServerRequest;
+import org.springframework.web.servlet.function.ServerResponse;
+import reactor.core.publisher.Mono;
+
+import java.io.IOException;
+import java.util.List;
+
+/**
+ * Implementation of a WebMVC based {@link McpStatelessServerTransport}.
+ *
+ * 

+ * This is the non-reactive version of
+ * {@link io.modelcontextprotocol.server.transport.WebFluxStatelessServerTransport}
+ *
+ * @author Christian Tzolov
+ */
+public class WebMvcStatelessServerTransport implements McpStatelessServerTransport {
+
+	private static final Logger logger = LoggerFactory.getLogger(WebMvcStatelessServerTransport.class);
+
+	private final ObjectMapper objectMapper;
+
+	private final String mcpEndpoint;
+
+	private final RouterFunction routerFunction;
+
+	private McpStatelessServerHandler mcpHandler;
+
+	private McpTransportContextExtractor contextExtractor;
+
+	private volatile boolean isClosing = false;
+
+	private WebMvcStatelessServerTransport(ObjectMapper objectMapper, String mcpEndpoint,
+			McpTransportContextExtractor contextExtractor) {
+		Assert.notNull(objectMapper, "objectMapper must not be null");
+		Assert.notNull(mcpEndpoint, "mcpEndpoint must not be null");
+		Assert.notNull(contextExtractor, "contextExtractor must not be null");
+
+		this.objectMapper = objectMapper;
+		this.mcpEndpoint = mcpEndpoint;
+		this.contextExtractor = contextExtractor;
+		this.routerFunction = RouterFunctions.route()
+			.GET(this.mcpEndpoint, this::handleGet)
+			.POST(this.mcpEndpoint, this::handlePost)
+			.build();
+	}
+
+	@Override
+	public void setMcpHandler(McpStatelessServerHandler mcpHandler) {
+		this.mcpHandler = mcpHandler;
+	}
+
+	@Override
+	public Mono closeGracefully() {
+		return Mono.fromRunnable(() -> this.isClosing = true);
+	}
+
+	/**
+	 * Returns the WebMVC router function that defines the transport's HTTP endpoints.
+	 * This router function should be integrated into the application's web configuration.
+	 *
+	 * 

+	 * The router function defines one endpoint handling two HTTP methods:
+	 * 
    
+	 * 
  • GET {messageEndpoint} - Unsupported, returns 405 METHOD NOT ALLOWED
    • 
+	 * 
  • POST {messageEndpoint} - For handling client requests and notifications
    • 
+	 * 

+	 * @return The configured {@link RouterFunction} for handling HTTP requests
+	 */
+	public RouterFunction getRouterFunction() {
+		return this.routerFunction;
+	}
+
+	private ServerResponse handleGet(ServerRequest request) {
+		return ServerResponse.status(HttpStatus.METHOD_NOT_ALLOWED).build();
+	}
+
+	private ServerResponse handlePost(ServerRequest request) {
+		if (isClosing) {
+			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
+		if (!(acceptHeaders.contains(MediaType.APPLICATION_JSON)
+				&& acceptHeaders.contains(MediaType.TEXT_EVENT_STREAM))) {
+			return ServerResponse.badRequest().build();
+		}
+
+		try {
+			String body = request.body(String.class);
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+
+			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
+				try {
+					McpSchema.JSONRPCResponse jsonrpcResponse = this.mcpHandler
+						.handleRequest(transportContext, jsonrpcRequest)
+						.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+						.block();
+					return ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(jsonrpcResponse);
+				}
+				catch (Exception e) {
+					logger.error("Failed to handle request: {}", e.getMessage());
+					return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
+						.body(new McpError("Failed to handle request: " + e.getMessage()));
+				}
+			}
+			else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
+				try {
+					this.mcpHandler.handleNotification(transportContext, jsonrpcNotification)
+						.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+						.block();
+					return ServerResponse.accepted().build();
+				}
+				catch (Exception e) {
+					logger.error("Failed to handle notification: {}", e.getMessage());
+					return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
+						.body(new McpError("Failed to handle notification: " + e.getMessage()));
+				}
+			}
+			else {
+				return ServerResponse.badRequest()
+					.body(new McpError("The server accepts either requests or notifications"));
+			}
+		}
+		catch (IllegalArgumentException | IOException e) {
+			logger.error("Failed to deserialize message: {}", e.getMessage());
+			return ServerResponse.badRequest().body(new McpError("Invalid message format"));
+		}
+		catch (Exception e) {
+			logger.error("Unexpected error handling message: {}", e.getMessage());
+			return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
+				.body(new McpError("Unexpected error: " + e.getMessage()));
+		}
+	}
+
+	/**
+	 * Create a builder for the server.
+	 * @return a fresh {@link Builder} instance.
+	 */
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for creating instances of {@link WebMvcStatelessServerTransport}.
+	 * 

+	 * This builder provides a fluent API for configuring and creating instances of
+	 * WebMvcStatelessServerTransport with custom settings.
+	 */
+	public static class Builder {
+
+		private ObjectMapper objectMapper;
+
+		private String mcpEndpoint = "/mcp";
+
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
+		private Builder() {
+			// used by a static method
+		}
+
+		/**
+		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * messages.
+		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public Builder objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint URI where clients should send their JSON-RPC messages.
+		 * @param messageEndpoint The message endpoint URI. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if messageEndpoint is null
+		 */
+		public Builder messageEndpoint(String messageEndpoint) {
+			Assert.notNull(messageEndpoint, "Message endpoint must not be null");
+			this.mcpEndpoint = messageEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets the context extractor that allows providing the MCP feature
+		 * implementations to inspect HTTP transport level metadata that was present at
+		 * HTTP request processing time. This allows to extract custom headers and other
+		 * useful data for use during execution later on in the process.
+		 * @param contextExtractor The contextExtractor to fill in a
+		 * {@link McpTransportContext}.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "Context extractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
+		/**
+		 * Builds a new instance of {@link WebMvcStatelessServerTransport} with the
+		 * configured settings.
+		 * @return A new WebMvcStatelessServerTransport instance
+		 * @throws IllegalStateException if required parameters are not set
+		 */
+		public WebMvcStatelessServerTransport build() {
+			Assert.notNull(objectMapper, "ObjectMapper must be set");
+			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
+
+			return new WebMvcStatelessServerTransport(objectMapper, mcpEndpoint, contextExtractor);
+		}
+
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
new file mode 100644
index 000000000..b2264ea00
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
@@ -0,0 +1,165 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol.server;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.Duration;
+
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerResponse;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.AbstractStatelessIntegrationTests;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.server.McpServer.StatelessAsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.StatelessSyncSpecification;
+import io.modelcontextprotocol.server.transport.WebMvcStatelessServerTransport;
+import io.modelcontextprotocol.spec.McpSchema;
+import reactor.core.scheduler.Schedulers;
+
+class WebMvcStatelessIntegrationTests extends AbstractStatelessIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String MESSAGE_ENDPOINT = "/mcp/message";
+
+	private WebMvcStatelessServerTransport mcpServerTransport;
+
+	@Configuration
+	@EnableWebMvc
+	static class TestConfig {
+
+		@Bean
+		public WebMvcStatelessServerTransport webMvcStatelessServerTransport() {
+
+			return WebMvcStatelessServerTransport.builder()
+				.objectMapper(new ObjectMapper())
+				.messageEndpoint(MESSAGE_ENDPOINT)
+				.build();
+
+		}
+
+		@Bean
+		public RouterFunction routerFunction(WebMvcStatelessServerTransport statelessServerTransport) {
+			return statelessServerTransport.getRouterFunction();
+		}
+
+	}
+
+	private TomcatTestUtil.TomcatServer tomcatServer;
+
+	@BeforeEach
+	public void before() {
+
+		tomcatServer = TomcatTestUtil.createTomcatServer("", PORT, TestConfig.class);
+
+		try {
+			tomcatServer.tomcat().start();
+			assertThat(tomcatServer.tomcat().getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+						.endpoint(MESSAGE_ENDPOINT)
+						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
+
+		clientBuilders.put("webflux",
+				McpClient.sync(WebClientStreamableHttpTransport
+					.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
+					.endpoint(MESSAGE_ENDPOINT)
+					.build()));
+
+		// Get the transport from Spring context
+		this.mcpServerTransport = tomcatServer.appContext().getBean(WebMvcStatelessServerTransport.class);
+
+	}
+
+	@Override
+	protected StatelessAsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(this.mcpServerTransport);
+	}
+
+	@Override
+	protected StatelessSyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(this.mcpServerTransport);
+	}
+
+	@AfterEach
+	public void after() {
+		reactor.netty.http.HttpResources.disposeLoopsAndConnections();
+		if (this.mcpServerTransport != null) {
+			this.mcpServerTransport.closeGracefully().block();
+		}
+		Schedulers.shutdownNow();
+		if (tomcatServer.appContext() != null) {
+			tomcatServer.appContext().close();
+		}
+		if (tomcatServer.tomcat() != null) {
+			try {
+				tomcatServer.tomcat().stop();
+				tomcatServer.tomcat().destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void simple(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var server = McpServer.async(this.mcpServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1000))
+			.build();
+
+		try (
+				// Create client without sampling capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+					.requestTimeout(Duration.ofSeconds(1000))
+					.build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+		}
+		server.closeGracefully();
+	}
+
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
+
+		clientBuilders.put("httpclient", McpClient
+			.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + port).endpoint(mcpEndpoint).build())
+			.initializationTimeout(Duration.ofHours(10))
+			.requestTimeout(Duration.ofHours(10)));
+
+		clientBuilders.put("webflux",
+				McpClient.sync(WebClientStreamableHttpTransport
+					.builder(WebClient.builder().baseUrl("http://localhost:" + port))
+					.endpoint(mcpEndpoint)
+					.build()));
+	}
+
+}
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
new file mode 100644
index 000000000..a84d127aa
--- /dev/null
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
@@ -0,0 +1,538 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol;
+
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.awaitility.Awaitility.await;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicReference;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.server.McpServer.StatelessAsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.StatelessSyncSpecification;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.McpStatelessSyncServer;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import net.javacrumbs.jsonunit.core.Option;
+import reactor.core.publisher.Mono;
+
+public abstract class AbstractStatelessIntegrationTests {
+
+	protected ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
+
+	abstract protected void prepareClients(int port, String mcpEndpoint);
+
+	abstract protected StatelessAsyncSpecification prepareAsyncServerBuilder();
+
+	abstract protected StatelessSyncSpecification prepareSyncServerBuilder();
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void simple(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.requestTimeout(Duration.ofSeconds(1000))
+			.build();
+
+		try (
+				// Create client without sampling capabilities
+				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+					.requestTimeout(Duration.ofSeconds(1000))
+					.build()) {
+
+			assertThat(client.initialize()).isNotNull();
+
+		}
+		server.closeGracefully();
+	}
+
+	// ---------------------------------------
+	// Tools Tests
+	// ---------------------------------------
+
+	String emptyJsonSchema = """
+			{
+				"$schema": "http://json-schema.org/draft-07/schema#",
+				"type": "object",
+				"properties": {}
+			}
+			""";
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolCallSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpStatelessServerFeatures.SyncToolSpecification tool1 = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((ctx, request) -> {
+
+				try {
+					HttpResponse response = HttpClient.newHttpClient()
+						.send(HttpRequest.newBuilder()
+							.uri(URI.create(
+									"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+							.GET()
+							.build(), HttpResponse.BodyHandlers.ofString());
+					String responseBody = response.body();
+					assertThat(responseBody).isNotBlank();
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+
+				return callResponse;
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull().isEqualTo(callResponse);
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		McpStatelessSyncServer mcpServer = prepareSyncServerBuilder()
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(McpStatelessServerFeatures.SyncToolSpecification.builder()
+				.tool(Tool.builder()
+					.name("tool1")
+					.description("tool1 description")
+					.inputSchema(emptyJsonSchema)
+					.build())
+				.callHandler((context, request) -> {
+					// We trigger a timeout on blocking read, raising an exception
+					Mono.never().block(Duration.ofSeconds(1));
+					return null;
+				})
+				.build())
+			.build();
+
+		try (var mcpClient = clientBuilder.requestTimeout(Duration.ofMillis(6666)).build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// We expect the tool call to fail immediately with the exception raised by
+			// the offending tool
+			// instead of getting back a timeout.
+			assertThatExceptionOfType(McpError.class)
+				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
+				.withMessageContaining("Timeout on blocking read");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolListChangeHandlingSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpStatelessServerFeatures.SyncToolSpecification tool1 = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((ctx, request) -> {
+				// perform a blocking call to a remote service
+				try {
+					HttpResponse response = HttpClient.newHttpClient()
+						.send(HttpRequest.newBuilder()
+							.uri(URI.create(
+									"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+							.GET()
+							.build(), HttpResponse.BodyHandlers.ofString());
+					String responseBody = response.body();
+					assertThat(responseBody).isNotBlank();
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+				return callResponse;
+			})
+			.build();
+
+		AtomicReference> rootsRef = new AtomicReference<>();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
+			// perform a blocking call to a remote service
+			try {
+				HttpResponse response = HttpClient.newHttpClient()
+					.send(HttpRequest.newBuilder()
+						.uri(URI.create(
+								"https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md"))
+						.GET()
+						.build(), HttpResponse.BodyHandlers.ofString());
+				String responseBody = response.body();
+				assertThat(responseBody).isNotBlank();
+			}
+			catch (Exception e) {
+				e.printStackTrace();
+			}
+
+			rootsRef.set(toolsUpdate);
+		}).build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(rootsRef.get()).isNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			// Remove a tool
+			mcpServer.removeTool("tool1");
+
+			// Add a new tool
+			McpStatelessServerFeatures.SyncToolSpecification tool2 = McpStatelessServerFeatures.SyncToolSpecification
+				.builder()
+				.tool(Tool.builder()
+					.name("tool2")
+					.description("tool2 description")
+					.inputSchema(emptyJsonSchema)
+					.build())
+				.callHandler((exchange, request) -> callResponse)
+				.build();
+
+			mcpServer.addTool(tool2);
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testInitialize(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var mcpServer = prepareSyncServerBuilder().build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				String expression = (String) request.arguments().getOrDefault("expression", "2 + 3");
+				double result = evaluateExpression(expression);
+				return CallToolResult.builder()
+					.structuredContent(
+							Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			// In WebMVC, structured content is returned properly
+			if (response.structuredContent() != null) {
+				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+					.containsEntry("operation", "2 + 3")
+					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
+			}
+			else {
+				// Fallback to checking content if structured content is not available
+				assertThat(response.content()).isNotEmpty();
+			}
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputValidationFailure(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				// Return invalid structured output. Result should be number, missing
+				// operation
+				return CallToolResult.builder()
+					.addTextContent("Invalid calculation")
+					.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputMissingStructuredContent(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		var tool = McpStatelessServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				// Return result without structured content but tool has output schema
+				return CallToolResult.builder().addTextContent("Calculation completed").build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputRuntimeToolAddition(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Start server without tools
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			var toolSpec = McpStatelessServerFeatures.SyncToolSpecification.builder()
+				.tool(dynamicTool)
+				.callHandler((exchange, request) -> {
+					int count = (Integer) request.arguments().getOrDefault("count", 1);
+					return CallToolResult.builder()
+						.addTextContent("Dynamic tool executed " + count + " times")
+						.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+						.build();
+				})
+				.build();
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
index f154272ef..8be59a779 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
@@ -22,6 +22,7 @@
  * support.
  *
  * @author Dariusz Jędrzejczyk
+ * @author Christian Tzolov
  */
 public class McpStatelessServerFeatures {
 
@@ -212,6 +213,59 @@ static AsyncToolSpecification fromSync(SyncToolSpecification syncToolSpec, boole
 
 			return new AsyncToolSpecification(syncToolSpec.tool(), callHandler);
 		}
+
+		/**
+		 * Builder for creating AsyncToolSpecification instances.
+		 */
+		public static class Builder {
+
+			private McpSchema.Tool tool;
+
+			private BiFunction> callHandler;
+
+			/**
+			 * Sets the tool definition.
+			 * @param tool The tool definition including name, description, and parameter
+			 * schema
+			 * @return this builder instance
+			 */
+			public Builder tool(McpSchema.Tool tool) {
+				this.tool = tool;
+				return this;
+			}
+
+			/**
+			 * Sets the call tool handler function.
+			 * @param callHandler The function that implements the tool's logic
+			 * @return this builder instance
+			 */
+			public Builder callHandler(
+					BiFunction> callHandler) {
+				this.callHandler = callHandler;
+				return this;
+			}
+
+			/**
+			 * Builds the AsyncToolSpecification instance.
+			 * @return a new AsyncToolSpecification instance
+			 * @throws IllegalArgumentException if required fields are not set
+			 */
+			public AsyncToolSpecification build() {
+				Assert.notNull(tool, "Tool must not be null");
+				Assert.notNull(callHandler, "Call handler function must not be null");
+
+				return new AsyncToolSpecification(tool, callHandler);
+			}
+
+		}
+
+		/**
+		 * Creates a new builder instance.
+		 * @return a new Builder instance
+		 */
+		public static Builder builder() {
+			return new Builder();
+		}
 	}
 
 	/**
@@ -324,6 +378,55 @@ static AsyncCompletionSpecification fromSync(SyncCompletionSpecification complet
 	 */
 	public record SyncToolSpecification(McpSchema.Tool tool,
 			BiFunction callHandler) {
+
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		/**
+		 * Builder for creating SyncToolSpecification instances.
+		 */
+		public static class Builder {
+
+			private McpSchema.Tool tool;
+
+			private BiFunction callHandler;
+
+			/**
+			 * Sets the tool definition.
+			 * @param tool The tool definition including name, description, and parameter
+			 * schema
+			 * @return this builder instance
+			 */
+			public Builder tool(McpSchema.Tool tool) {
+				this.tool = tool;
+				return this;
+			}
+
+			/**
+			 * Sets the call tool handler function.
+			 * @param callHandler The function that implements the tool's logic
+			 * @return this builder instance
+			 */
+			public Builder callHandler(
+					BiFunction callHandler) {
+				this.callHandler = callHandler;
+				return this;
+			}
+
+			/**
+			 * Builds the SyncToolSpecification instance.
+			 * @return a new SyncToolSpecification instance
+			 * @throws IllegalArgumentException if required fields are not set
+			 */
+			public SyncToolSpecification build() {
+				Assert.notNull(tool, "Tool must not be null");
+				Assert.notNull(callHandler, "CallTool function must not be null");
+
+				return new SyncToolSpecification(tool, callHandler);
+			}
+
+		}
 	}
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
new file mode 100644
index 000000000..25b003564
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
@@ -0,0 +1,306 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server.transport;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.PrintWriter;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpStatelessServerHandler;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpStatelessServerTransport;
+import io.modelcontextprotocol.util.Assert;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.annotation.WebServlet;
+import jakarta.servlet.http.HttpServlet;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import reactor.core.publisher.Mono;
+
+/**
+ * Implementation of an HttpServlet based {@link McpStatelessServerTransport}.
+ *
+ * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
+ */
+@WebServlet(asyncSupported = true)
+public class HttpServletStatelessServerTransport extends HttpServlet implements McpStatelessServerTransport {
+
+	private static final Logger logger = LoggerFactory.getLogger(HttpServletStatelessServerTransport.class);
+
+	public static final String UTF_8 = "UTF-8";
+
+	public static final String APPLICATION_JSON = "application/json";
+
+	public static final String TEXT_EVENT_STREAM = "text/event-stream";
+
+	public static final String ACCEPT = "Accept";
+
+	public static final String FAILED_TO_SEND_ERROR_RESPONSE = "Failed to send error response: {}";
+
+	private final ObjectMapper objectMapper;
+
+	private final String mcpEndpoint;
+
+	private McpStatelessServerHandler mcpHandler;
+
+	private McpTransportContextExtractor contextExtractor;
+
+	private volatile boolean isClosing = false;
+
+	private HttpServletStatelessServerTransport(ObjectMapper objectMapper, String mcpEndpoint,
+			McpTransportContextExtractor contextExtractor) {
+		Assert.notNull(objectMapper, "objectMapper must not be null");
+		Assert.notNull(mcpEndpoint, "mcpEndpoint must not be null");
+		Assert.notNull(contextExtractor, "contextExtractor must not be null");
+
+		this.objectMapper = objectMapper;
+		this.mcpEndpoint = mcpEndpoint;
+		this.contextExtractor = contextExtractor;
+	}
+
+	@Override
+	public void setMcpHandler(McpStatelessServerHandler mcpHandler) {
+		this.mcpHandler = mcpHandler;
+	}
+
+	@Override
+	public Mono closeGracefully() {
+		return Mono.fromRunnable(() -> this.isClosing = true);
+	}
+
+	/**
+	 * Handles GET requests - returns 405 METHOD NOT ALLOWED as stateless transport
+	 * doesn't support GET requests.
+	 * @param request The HTTP servlet request
+	 * @param response The HTTP servlet response
+	 * @throws ServletException If a servlet-specific error occurs
+	 * @throws IOException If an I/O error occurs
+	 */
+	@Override
+	protected void doGet(HttpServletRequest request, HttpServletResponse response)
+			throws ServletException, IOException {
+
+		String requestURI = request.getRequestURI();
+		if (!requestURI.endsWith(mcpEndpoint)) {
+			response.sendError(HttpServletResponse.SC_NOT_FOUND);
+			return;
+		}
+
+		response.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED);
+	}
+
+	/**
+	 * Handles POST requests for incoming JSON-RPC messages from clients.
+	 * @param request The HTTP servlet request containing the JSON-RPC message
+	 * @param response The HTTP servlet response
+	 * @throws ServletException If a servlet-specific error occurs
+	 * @throws IOException If an I/O error occurs
+	 */
+	@Override
+	protected void doPost(HttpServletRequest request, HttpServletResponse response)
+			throws ServletException, IOException {
+
+		String requestURI = request.getRequestURI();
+		if (!requestURI.endsWith(mcpEndpoint)) {
+			response.sendError(HttpServletResponse.SC_NOT_FOUND);
+			return;
+		}
+
+		if (isClosing) {
+			response.sendError(HttpServletResponse.SC_SERVICE_UNAVAILABLE, "Server is shutting down");
+			return;
+		}
+
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
+		String accept = request.getHeader(ACCEPT);
+		if (accept == null || !(accept.contains(APPLICATION_JSON) && accept.contains(TEXT_EVENT_STREAM))) {
+			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
+					new McpError("Both application/json and text/event-stream required in Accept header"));
+			return;
+		}
+
+		try {
+			BufferedReader reader = request.getReader();
+			StringBuilder body = new StringBuilder();
+			String line;
+			while ((line = reader.readLine()) != null) {
+				body.append(line);
+			}
+
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body.toString());
+
+			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
+				try {
+					McpSchema.JSONRPCResponse jsonrpcResponse = this.mcpHandler
+						.handleRequest(transportContext, jsonrpcRequest)
+						.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+						.block();
+
+					response.setContentType(APPLICATION_JSON);
+					response.setCharacterEncoding(UTF_8);
+					response.setStatus(HttpServletResponse.SC_OK);
+
+					String jsonResponseText = objectMapper.writeValueAsString(jsonrpcResponse);
+					PrintWriter writer = response.getWriter();
+					writer.write(jsonResponseText);
+					writer.flush();
+				}
+				catch (Exception e) {
+					logger.error("Failed to handle request: {}", e.getMessage());
+					this.responseError(response, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
+							new McpError("Failed to handle request: " + e.getMessage()));
+				}
+			}
+			else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
+				try {
+					this.mcpHandler.handleNotification(transportContext, jsonrpcNotification)
+						.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
+						.block();
+					response.setStatus(HttpServletResponse.SC_ACCEPTED);
+				}
+				catch (Exception e) {
+					logger.error("Failed to handle notification: {}", e.getMessage());
+					this.responseError(response, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
+							new McpError("Failed to handle notification: " + e.getMessage()));
+				}
+			}
+			else {
+				this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
+						new McpError("The server accepts either requests or notifications"));
+			}
+		}
+		catch (IllegalArgumentException | IOException e) {
+			logger.error("Failed to deserialize message: {}", e.getMessage());
+			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST, new McpError("Invalid message format"));
+		}
+		catch (Exception e) {
+			logger.error("Unexpected error handling message: {}", e.getMessage());
+			this.responseError(response, HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
+					new McpError("Unexpected error: " + e.getMessage()));
+		}
+	}
+
+	/**
+	 * Sends an error response to the client.
+	 * @param response The HTTP servlet response
+	 * @param httpCode The HTTP status code
+	 * @param mcpError The MCP error to send
+	 * @throws IOException If an I/O error occurs
+	 */
+	private void responseError(HttpServletResponse response, int httpCode, McpError mcpError) throws IOException {
+		response.setContentType(APPLICATION_JSON);
+		response.setCharacterEncoding(UTF_8);
+		response.setStatus(httpCode);
+		String jsonError = objectMapper.writeValueAsString(mcpError);
+		PrintWriter writer = response.getWriter();
+		writer.write(jsonError);
+		writer.flush();
+	}
+
+	/**
+	 * Cleans up resources when the servlet is being destroyed.
+	 * 

+	 * This method ensures a graceful shutdown before calling the parent's destroy method.
+	 */
+	@Override
+	public void destroy() {
+		closeGracefully().block();
+		super.destroy();
+	}
+
+	/**
+	 * Create a builder for the server.
+	 * @return a fresh {@link Builder} instance.
+	 */
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for creating instances of {@link HttpServletStatelessServerTransport}.
+	 * 

+	 * This builder provides a fluent API for configuring and creating instances of
+	 * HttpServletStatelessServerTransport with custom settings.
+	 */
+	public static class Builder {
+
+		private ObjectMapper objectMapper;
+
+		private String mcpEndpoint = "/mcp";
+
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
+		private Builder() {
+			// used by a static method
+		}
+
+		/**
+		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * messages.
+		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if objectMapper is null
+		 */
+		public Builder objectMapper(ObjectMapper objectMapper) {
+			Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			this.objectMapper = objectMapper;
+			return this;
+		}
+
+		/**
+		 * Sets the endpoint URI where clients should send their JSON-RPC messages.
+		 * @param messageEndpoint The message endpoint URI. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if messageEndpoint is null
+		 */
+		public Builder messageEndpoint(String messageEndpoint) {
+			Assert.notNull(messageEndpoint, "Message endpoint must not be null");
+			this.mcpEndpoint = messageEndpoint;
+			return this;
+		}
+
+		/**
+		 * Sets the context extractor that allows providing the MCP feature
+		 * implementations to inspect HTTP transport level metadata that was present at
+		 * HTTP request processing time. This allows to extract custom headers and other
+		 * useful data for use during execution later on in the process.
+		 * @param contextExtractor The contextExtractor to fill in a
+		 * {@link McpTransportContext}.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "Context extractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
+		/**
+		 * Builds a new instance of {@link HttpServletStatelessServerTransport} with the
+		 * configured settings.
+		 * @return A new HttpServletStatelessServerTransport instance
+		 * @throws IllegalStateException if required parameters are not set
+		 */
+		public HttpServletStatelessServerTransport build() {
+			Assert.notNull(objectMapper, "ObjectMapper must be set");
+			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
+
+			return new HttpServletStatelessServerTransport(objectMapper, mcpEndpoint, contextExtractor);
+		}
+
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
new file mode 100644
index 000000000..da8aa4adf
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -0,0 +1,473 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+package io.modelcontextprotocol.server;
+
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
+
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.web.client.RestClient;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
+import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.Prompt;
+import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.Tool;
+import net.javacrumbs.jsonunit.core.Option;
+
+class HttpServletStatelessIntegrationTests {
+
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
+	private static final String CUSTOM_MESSAGE_ENDPOINT = "/otherPath/mcp/message";
+
+	private HttpServletStatelessServerTransport mcpStatelessServerTransport;
+
+	ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
+
+	private Tomcat tomcat;
+
+	@BeforeEach
+	public void before() {
+		this.mcpStatelessServerTransport = HttpServletStatelessServerTransport.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
+			.build();
+
+		tomcat = TomcatTestUtil.createTomcatServer("", PORT, mcpStatelessServerTransport);
+		try {
+			tomcat.start();
+			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+						.endpoint(CUSTOM_MESSAGE_ENDPOINT)
+						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
+	}
+
+	@AfterEach
+	public void after() {
+		if (mcpStatelessServerTransport != null) {
+			mcpStatelessServerTransport.closeGracefully().block();
+		}
+		if (tomcat != null) {
+			try {
+				tomcat.stop();
+				tomcat.destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	// ---------------------------------------
+	// Tools Tests
+	// ---------------------------------------
+
+	String emptyJsonSchema = """
+			{
+			"$schema": "http://json-schema.org/draft-07/schema#",
+			"type": "object",
+			"properties": {}
+			}
+			""";
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testToolCallSuccess(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		McpStatelessServerFeatures.SyncToolSpecification tool1 = new McpStatelessServerFeatures.SyncToolSpecification(
+				new Tool("tool1", "tool1 description", emptyJsonSchema), (transportContext, request) -> {
+					// perform a blocking call to a remote service
+					String response = RestClient.create()
+						.get()
+						.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
+						.retrieve()
+						.body(String.class);
+					assertThat(response).isNotBlank();
+					return callResponse;
+				});
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testInitialize(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport).build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Completion Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : Completion call")
+	@ValueSource(strings = { "httpclient" })
+	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var expectedValues = List.of("python", "pytorch", "pyside");
+		var completionResponse = new CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
+				true // hasMore
+		));
+
+		AtomicReference samplingRequest = new AtomicReference<>();
+		BiFunction completionHandler = (transportContext,
+				request) -> {
+			samplingRequest.set(request);
+			return completionResponse;
+		};
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.capabilities(ServerCapabilities.builder().completions().build())
+			.prompts(new McpStatelessServerFeatures.SyncPromptSpecification(
+					new Prompt("code_review", "Code review", "this is code review prompt",
+							List.of(new PromptArgument("language", "Language", "string", false))),
+					(transportContext, getPromptRequest) -> null))
+			.completions(new McpStatelessServerFeatures.SyncCompletionSpecification(
+					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CompleteRequest request = new CompleteRequest(
+					new PromptReference("ref/prompt", "code_review", "Code review"),
+					new CompleteRequest.CompleteArgument("language", "py"));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			assertThat(result).isNotNull();
+
+			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
+			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Tool Structured Output Schema Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
+				calculatorTool, (transportContext, request) -> {
+					String expression = (String) request.arguments().getOrDefault("expression", "2 + 3");
+					double result = evaluateExpression(expression);
+					return CallToolResult.builder()
+						.structuredContent(
+								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputValidationFailure(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+				List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
+				calculatorTool, (transportContext, request) -> {
+					// Return invalid structured output. Result should be number, missing
+					// operation
+					return CallToolResult.builder()
+						.addTextContent("Invalid calculation")
+						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
+						.build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool with invalid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).contains("Validation failed");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputMissingStructuredContent(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of("type", "object", "properties",
+				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
+				calculatorTool, (transportContext, request) -> {
+					// Return result without structured content but tool has output schema
+					return CallToolResult.builder().addTextContent("Calculation completed").build();
+				});
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.instructions("bla")
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call tool that should return structured content but doesn't
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+
+			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
+			assertThat(errorMessage).isEqualTo(
+					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
+		}
+
+		mcpServer.close();
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputRuntimeToolAddition(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Start server without tools
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Initially no tools
+			assertThat(mcpClient.listTools().tools()).isEmpty();
+
+			// Add tool with output schema at runtime
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
+					List.of("message", "count"));
+
+			Tool dynamicTool = Tool.builder()
+				.name("dynamic-tool")
+				.description("Dynamically added tool")
+				.outputSchema(outputSchema)
+				.build();
+
+			McpStatelessServerFeatures.SyncToolSpecification toolSpec = new McpStatelessServerFeatures.SyncToolSpecification(
+					dynamicTool, (transportContext, request) -> {
+						int count = (Integer) request.arguments().getOrDefault("count", 1);
+						return CallToolResult.builder()
+							.addTextContent("Dynamic tool executed " + count + " times")
+							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
+							.build();
+					});
+
+			// Add tool to server
+			mcpServer.addTool(toolSpec);
+
+			// Wait for tool list change notification
+			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
+				assertThat(mcpClient.listTools().tools()).hasSize(1);
+			});
+
+			// Verify tool was added with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call dynamically added tool
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+			assertThat(response.content()).hasSize(1);
+			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
+				.isEqualTo("Dynamic tool executed 3 times");
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isObject()
+				.isEqualTo(json("""
+						{"count":3,"message":"Dynamic execution"}"""));
+		}
+
+		mcpServer.close();
+	}
+
+	private double evaluateExpression(String expression) {
+		// Simple expression evaluator for testing
+		return switch (expression) {
+			case "2 + 3" -> 5.0;
+			case "10 * 2" -> 20.0;
+			case "7 + 8" -> 15.0;
+			case "5 + 3" -> 8.0;
+			default -> 0.0;
+		};
+	}
+
+}

From 34d2d84669336bea9fbd41206b677f991d201aad Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 02:06:40 +0200
Subject: [PATCH 027/125] Add missing POM descriptions

Signed-off-by: Christian Tzolov 
---
 mcp-spring/mcp-spring-webflux/pom.xml | 4 ++--
 mcp-spring/mcp-spring-webmvc/pom.xml  | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index fdec82377..9008e52da 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -11,8 +11,8 @@
 	
 	mcp-spring-webflux
 	jar
-	WebFlux implementation of the Java MCP SSE transport
-	
+	WebFlux transports
+	WebFlux implementation for the SSE and Streamable Http Client and Server transports
 	https://github.com/modelcontextprotocol/java-sdk
 
 	
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 4b8c684ab..0a18bf711 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -11,8 +11,8 @@
 	
 	mcp-spring-webmvc
 	jar
-	Spring Web MVC implementation of the Java MCP SSE transport
-	
+	Spring Web MVC transports
+	Web MVC implementation for the SSE and Streamable Http Server transports
 	https://github.com/modelcontextprotocol/java-sdk
 
 	

From 6384d794b123a5dd25a988d1ec88077caa71b47a Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 02:07:49 +0200
Subject: [PATCH 028/125] Release version 0.11.0

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 7214dacda..8e1a3d4d0 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.11.0-SNAPSHOT
+        0.11.0
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 9008e52da..fae20dd87 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.11.0
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0-SNAPSHOT
+			0.11.0
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 0a18bf711..a6a2a22fc 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.11.0
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0-SNAPSHOT
+			0.11.0
 			test
 		
 
 				
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.11.0-SNAPSHOT
+			0.11.0
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index cc34e96d4..0a6d59f92 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.11.0
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index de4ee988a..3a9618099 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index b7a66aeec..17b94fbbd 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.11.0-SNAPSHOT
+	0.11.0
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From bead5321e3a52b9012451be74e1349d594801eb7 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 02:08:14 +0200
Subject: [PATCH 029/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 8e1a3d4d0..6e8c38bc8 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.11.0
+        0.11.1-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index fae20dd87..dba8ce605 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0
+			0.11.1-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0
+			0.11.1-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index a6a2a22fc..9bc190589 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0
+			0.11.1-SNAPSHOT
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0
+			0.11.1-SNAPSHOT
 			test
 		
 
 				
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.11.0
+			0.11.1-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 0a6d59f92..933e1d968 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0
+			0.11.1-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 3a9618099..1615b8985 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index 17b94fbbd..d95aab0f7 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.11.0
+	0.11.1-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From 1664401d0c69634373acef1b26d7f6ed52a08d0c Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 02:10:22 +0200
Subject: [PATCH 030/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 6e8c38bc8..7214dacda 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.11.1-SNAPSHOT
+        0.11.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index dba8ce605..9008e52da 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 9bc190589..0a18bf711 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 			test
 		
 
 				
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 933e1d968..cc34e96d4 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 1615b8985..de4ee988a 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index d95aab0f7..b7a66aeec 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.11.1-SNAPSHOT
+	0.11.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From b4887ad8e1c478c0f544228294f5c0a891524401 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 02:25:34 +0200
Subject: [PATCH 031/125] Release version 0.11.0

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 7214dacda..8e1a3d4d0 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.11.0-SNAPSHOT
+        0.11.0
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 9008e52da..fae20dd87 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.11.0
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0-SNAPSHOT
+			0.11.0
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 0a18bf711..a6a2a22fc 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.11.0
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0-SNAPSHOT
+			0.11.0
 			test
 		
 
 				
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.11.0-SNAPSHOT
+			0.11.0
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index cc34e96d4..0a6d59f92 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.11.0
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index de4ee988a..3a9618099 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.11.0
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index b7a66aeec..17b94fbbd 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.11.0-SNAPSHOT
+	0.11.0
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From 8dcb21773f34fa52fd143605fc216464e8f9abac Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 02:26:59 +0200
Subject: [PATCH 032/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 8e1a3d4d0..6e8c38bc8 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.11.0
+        0.11.1-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index fae20dd87..dba8ce605 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0
+			0.11.1-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0
+			0.11.1-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index a6a2a22fc..9bc190589 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0
+			0.11.1-SNAPSHOT
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0
+			0.11.1-SNAPSHOT
 			test
 		
 
 				
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.11.0
+			0.11.1-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 0a6d59f92..933e1d968 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0
+			0.11.1-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 3a9618099..1615b8985 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0
+		0.11.1-SNAPSHOT
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index 17b94fbbd..d95aab0f7 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.11.0
+	0.11.1-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From 28edd3630a0e6f9f03c7b319a16bd2f57d5735dd Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 02:29:41 +0200
Subject: [PATCH 033/125] revert

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 6e8c38bc8..7214dacda 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.11.1-SNAPSHOT
+        0.11.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index dba8ce605..9008e52da 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 9bc190589..0a18bf711 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 			test
 		
 
 				
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 933e1d968..cc34e96d4 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.1-SNAPSHOT
+			0.11.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 1615b8985..de4ee988a 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.1-SNAPSHOT
+		0.11.0-SNAPSHOT
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index d95aab0f7..b7a66aeec 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.11.1-SNAPSHOT
+	0.11.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From bf2c8c955cab530ae70f4b8a9c6b2e221cb7bcba Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 31 Jul 2025 03:34:02 +0200
Subject: [PATCH 034/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 7214dacda..83d8bc510 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.11.0-SNAPSHOT
+        0.12.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 9008e52da..300d518e7 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.12.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.12.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0-SNAPSHOT
+			0.12.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 0a18bf711..ea262d3a1 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.12.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.12.0-SNAPSHOT
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.11.0-SNAPSHOT
+			0.12.0-SNAPSHOT
 			test
 		
 
 				
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.11.0-SNAPSHOT
+			0.12.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index cc34e96d4..563f60de9 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.12.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.11.0-SNAPSHOT
+			0.12.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index de4ee988a..1cf61c48f 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.11.0-SNAPSHOT
+		0.12.0-SNAPSHOT
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index b7a66aeec..c0b1f7a44 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.11.0-SNAPSHOT
+	0.12.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From 3e4d5dedaf5f941b3e44b046d15ba6df79ecd198 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Fri, 1 Aug 2025 16:06:02 +0100
Subject: [PATCH 035/125] Update copyright headers to 2025 and clean up code

- Add copyright headers to files missing them
- Add blank lines after copyright headers for consistency
- Remove unused imports in test files
- Remove unnecessary keep-alive warning logs in WebFlux and WebMvc transport providers

Signed-off-by: Christian Tzolov 
---
 .../WebClientStreamableHttpTransport.java       |  4 ++++
 .../transport/WebFluxSseClientTransport.java    |  1 +
 .../WebFluxSseServerTransportProvider.java      |  4 ++++
 .../WebFluxStatelessServerTransport.java        |  4 ++++
 ...ebFluxStreamableServerTransportProvider.java |  8 ++++----
 .../WebFluxSseIntegrationTests.java             |  1 +
 .../WebFluxStatelessIntegrationTests.java       |  1 +
 .../WebFluxStreamableIntegrationTests.java      |  1 +
 ...treamableHttpAsyncClientResiliencyTests.java |  4 ++++
 ...WebClientStreamableHttpAsyncClientTests.java |  4 ++++
 .../WebClientStreamableHttpSyncClientTests.java |  4 ++++
 .../WebFluxStreamableMcpAsyncServerTests.java   |  2 --
 .../WebFluxStreamableMcpSyncServerTests.java    |  1 -
 .../server/transport/BlockingInputStream.java   |  1 +
 .../WebMvcStatelessServerTransport.java         |  4 ++++
 ...WebMvcStreamableServerTransportProvider.java |  6 ------
 ...AbstractMcpClientServerIntegrationTests.java |  1 +
 .../AbstractStatelessIntegrationTests.java      |  1 +
 .../AbstractMcpAsyncClientResiliencyTests.java  |  1 +
 .../modelcontextprotocol/server/TestUtil.java   |  1 +
 .../client/LifecycleInitializer.java            |  4 ++++
 .../client/McpAsyncClient.java                  |  1 +
 .../transport/HttpClientSseClientTransport.java |  1 +
 .../client/transport/ResponseSubscribers.java   |  1 +
 .../DefaultMcpStatelessServerHandler.java       |  4 ++++
 .../server/DefaultMcpTransportContext.java      |  4 ++++
 .../server/McpInitRequestHandler.java           |  4 ++++
 .../server/McpStatelessNotificationHandler.java |  4 ++++
 .../server/McpStatelessRequestHandler.java      |  4 ++++
 .../server/McpStatelessServerHandler.java       |  4 ++++
 .../server/McpSyncServer.java                   |  1 -
 .../server/McpTransportContext.java             |  4 ++++
 .../server/McpTransportContextExtractor.java    |  4 ++++
 .../HttpServletSseServerTransportProvider.java  |  1 +
 .../spec/DefaultJsonSchemaValidator.java        |  1 +
 ...efaultMcpStreamableServerSessionFactory.java |  5 ++++-
 .../spec/DefaultMcpTransportSession.java        |  4 ++++
 .../spec/DefaultMcpTransportStream.java         |  4 ++++
 .../modelcontextprotocol/spec/HttpHeaders.java  |  4 ++++
 .../spec/JsonSchemaValidator.java               |  1 +
 .../spec/McpClientTransport.java                |  1 +
 .../io/modelcontextprotocol/spec/McpError.java  |  1 +
 .../spec/McpLoggableSession.java                |  4 ++++
 .../spec/McpServerSession.java                  |  4 ++++
 .../spec/McpServerTransport.java                |  4 ++++
 .../spec/McpServerTransportProvider.java        |  4 ++++
 .../spec/McpServerTransportProviderBase.java    |  4 ++++
 .../modelcontextprotocol/spec/McpSession.java   |  1 -
 .../spec/McpStatelessServerTransport.java       |  4 ++++
 .../spec/McpStreamableServerSession.java        |  4 ++++
 .../spec/McpStreamableServerTransport.java      |  4 ++++
 .../McpStreamableServerTransportProvider.java   |  4 ++++
 .../spec/McpTransportSession.java               |  4 ++++
 .../McpTransportSessionNotFoundException.java   |  4 ++++
 .../spec/McpTransportStream.java                |  4 ++++
 .../spec/MissingMcpTransportSession.java        |  4 ++++
 .../DeafaultMcpUriTemplateManagerFactory.java   |  1 +
 .../util/KeepAliveScheduler.java                |  1 +
 .../util/McpUriTemplateManagerFactory.java      |  1 +
 .../MockMcpServerTransportProvider.java         | 17 +++--------------
 .../AbstractMcpAsyncClientResiliencyTests.java  |  1 +
 ...ttpClientStreamableHttpAsyncClientTests.java |  4 ++++
 ...HttpClientStreamableHttpSyncClientTests.java |  4 ++++
 .../client/McpAsyncClientTests.java             |  4 ++++
 ...AbstractMcpClientServerIntegrationTests.java |  1 +
 .../HttpServletStatelessIntegrationTests.java   |  1 +
 .../HttpServletStreamableIntegrationTests.java  |  1 +
 .../server/McpCompletionTests.java              |  4 ++++
 .../server/McpSyncServerExchangeTests.java      |  1 -
 ...pServletSseServerCustomContextPathTests.java |  1 +
 ...ServerTransportProviderIntegrationTests.java |  2 +-
 .../server/transport/TomcatTestUtil.java        |  1 +
 .../spec/ArgumentException.java                 |  4 ++++
 .../spec/DefaultJsonSchemaValidatorTests.java   |  2 +-
 .../spec/McpSchemaTests.java                    |  1 +
 75 files changed, 188 insertions(+), 33 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index d7f7f9bfb..b7b544660 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client.transport;
 
 import java.io.IOException;
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
index fe6b07a6d..f122c8fab 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.client.transport;
 
 import java.io.IOException;
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index 67810fb56..c2c2c2ea6 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server.transport;
 
 import java.io.IOException;
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
index c514f2dff..23fff25b3 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server.transport;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index 00ec68c5d..b9111d638 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server.transport;
 
 import com.fasterxml.jackson.core.type.TypeReference;
@@ -89,10 +93,6 @@ private WebFluxStreamableServerTransportProvider(ObjectMapper objectMapper, Stri
 
 			this.keepAliveScheduler.start();
 		}
-		else {
-			logger.warn("Keep-alive interval is not set or invalid. No keep-alive will be scheduled.");
-		}
-
 	}
 
 	@Override
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index 23ddf6173..8ce714f94 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol;
 
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
index 2f1765df7..0327e6b53 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
index bc13ad9c6..5cd19e627 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java
index 7c4d35db8..191f10376 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientResiliencyTests.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client;
 
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
index 5ff707b3c..f8a16c153 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client;
 
 import org.junit.jupiter.api.Timeout;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
index 70260c8bf..5e9960d0e 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client;
 
 import org.junit.jupiter.api.Timeout;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
index 928bd812d..959f2f472 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
@@ -5,9 +5,7 @@
 package io.modelcontextprotocol.server;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
-import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
 import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
-import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
 import org.springframework.http.server.reactive.HttpHandler;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
index e82e384c4..3396d489c 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
@@ -5,7 +5,6 @@
 package io.modelcontextprotocol.server;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
-import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
 import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/transport/BlockingInputStream.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/transport/BlockingInputStream.java
index 0ab72a99f..dfb004e9b 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/transport/BlockingInputStream.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/transport/BlockingInputStream.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2024 - 2024 the original author or authors.
 */
+
 package io.modelcontextprotocol.server.transport;
 
 import java.io.IOException;
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
index 1b026fc46..fef1920fc 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server.transport;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index 2f94d5c11..4a2117ca4 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -95,9 +95,6 @@ public class WebMvcStreamableServerTransportProvider implements McpStreamableSer
 
 	private McpTransportContextExtractor contextExtractor;
 
-	// private Function contextExtractor = req -> new
-	// DefaultMcpTransportContext();
-
 	/**
 	 * Flag indicating if the transport is shutting down.
 	 */
@@ -142,9 +139,6 @@ private WebMvcStreamableServerTransportProvider(ObjectMapper objectMapper, Strin
 
 			this.keepAliveScheduler.start();
 		}
-		else {
-			logger.warn("Keep-alive interval is not set or invalid. No keep-alive will be scheduled.");
-		}
 	}
 
 	@Override
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index d3d4fc071..b3a699b94 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol;
 
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
index a84d127aa..618247d61 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol;
 
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index 22e8f195b..ed34ebff6 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024-2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.client;
 
 import eu.rekawek.toxiproxy.Proxy;
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/TestUtil.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/TestUtil.java
index 0085f31ed..dbbf1a537 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/TestUtil.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/TestUtil.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2025 - 2025 the original author or authors.
 */
+
 package io.modelcontextprotocol.server;
 
 import java.io.IOException;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
index e33fafa6a..4eb94daa5 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client;
 
 import java.time.Duration;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 73765122f..27d9d2e6c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024-2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.client;
 
 import java.time.Duration;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 3fe88fec8..62c34fb8f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2025 the original author or authors.
  */
+
 package io.modelcontextprotocol.client.transport;
 
 import java.io.IOException;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
index eb9d3c65c..1ac559d78 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2024 - 2024 the original author or authors.
 */
+
 package io.modelcontextprotocol.client.transport;
 
 import java.net.http.HttpResponse;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
index 234a1d4a0..9a1f6e84e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import io.modelcontextprotocol.spec.McpError;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
index 300bdf711..9e18e189d 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import java.util.Map;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
index 609744637..13ff45a54 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import io.modelcontextprotocol.spec.McpSchema;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
index d9269a59b..6db79a62c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import reactor.core.publisher.Mono;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
index a6bf0d073..e5c9e7c09 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import reactor.core.publisher.Mono;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
index 80884435e..7c4e23cfc 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import io.modelcontextprotocol.spec.McpSchema;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
index 38f5128e4..5adda1a74 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import io.modelcontextprotocol.server.McpServerFeatures.AsyncToolSpecification;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 import io.modelcontextprotocol.util.Assert;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
index 3d51bb6e2..1cd540f72 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import java.util.Collections;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
index 472de8195..97fcecf0d 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index 24e749fc3..40d293216 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.server.transport;
 
 import java.io.BufferedReader;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
index cd8fc9659..f4bdc02eb 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024-2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.spec;
 
 import java.util.Map;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
index 8533e69cf..f497afd43 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
@@ -1,8 +1,11 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import io.modelcontextprotocol.server.McpNotificationHandler;
 import io.modelcontextprotocol.server.McpRequestHandler;
-import reactor.core.publisher.Mono;
 
 import java.time.Duration;
 import java.util.Map;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java
index 56cdeaf7f..fdb7bfd89 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import org.reactivestreams.Publisher;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java
index eb2b7edeb..8d63fb50d 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import org.reactivestreams.Publisher;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
index c1c4c7a7d..7c0aeacc4 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java b/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
index c95e627a9..572d7c043 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024-2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.spec;
 
 import java.util.Map;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java
index 5c3b33131..22aec831b 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2024 - 2024 the original author or authors.
 */
+
 package io.modelcontextprotocol.spec;
 
 import java.util.function.Consumer;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java
index 13e43240b..7193237bb 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2024 - 2024 the original author or authors.
 */
+
 package io.modelcontextprotocol.spec;
 
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse.JSONRPCError;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
index ebc6e0949..f43a2c1d9 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index 0b0ef01cd..538023e82 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import java.time.Duration;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java
index 632b8cee6..39c1644e0 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
index 382c0153b..02028ccdf 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
index 798575017..d1b252a26 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import java.util.Map;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
index 7b29ca651..42d170db5 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
@@ -5,7 +5,6 @@
 package io.modelcontextprotocol.spec;
 
 import com.fasterxml.jackson.core.type.TypeReference;
-import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Mono;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
index 329908469..14ed54438 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
index c9b041fd6..3eec75c09 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import java.time.Duration;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
index 39e90ce86..f53c68900 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import reactor.core.publisher.Mono;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
index b75081096..09fe9fb0e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import reactor.core.publisher.Mono;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
index 555f018f8..716ff0d16 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import org.reactivestreams.Publisher;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java
index 474a18ae0..eced49ec3 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java
index 2d6dcce75..322afda63 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import org.reactivestreams.Publisher;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
index c83f0bead..aa33a8167 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java b/mcp/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
index 3870b76fc..44ea31690 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2025 - 2025 the original author or authors.
 */
+
 package io.modelcontextprotocol.util;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java b/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
index 30e8a2c2a..9d411cd41 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
@@ -1,6 +1,7 @@
 /**
  * Copyright 2025 - 2025 the original author or authors.
  */
+
 package io.modelcontextprotocol.util;
 
 import java.time.Duration;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java b/mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java
index 9644f9a6c..389727b45 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2025 - 2025 the original author or authors.
 */
+
 package io.modelcontextprotocol.util;
 
 /**
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java b/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java
index 7ba35bbf0..e955be89f 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java
@@ -1,18 +1,7 @@
 /*
-* Copyright 2025 - 2025 the original author or authors.
-*
-* Licensed under the Apache License, Version 2.0 (the "License");
-* you may not use this file except in compliance with the License.
-* You may obtain a copy of the License at
-*
-* https://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
+ * Copyright 2025-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol;
 
 import io.modelcontextprotocol.spec.McpSchema;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index b673ed612..ec23e21dc 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024-2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.client;
 
 import eu.rekawek.toxiproxy.Proxy;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
index aa081b51b..aef2ab8dd 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client;
 
 import org.junit.jupiter.api.Timeout;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
index 8285f417f..7f00de60e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client;
 
 import org.junit.jupiter.api.Timeout;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
index 7b6777cbe..2c0331f4d 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.client;
 
 import com.fasterxml.jackson.core.type.TypeReference;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index 687ff6ae9..a53501898 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.server;
 
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index da8aa4adf..00942226f 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.server;
 
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index ecb0c33c3..07c6e7c5c 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.server;
 
 import static org.assertj.core.api.Assertions.assertThat;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
index e6e80efb0..e329188f9 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.server;
 
 import java.util.List;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
index 63d827013..a73ec7209 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
@@ -24,7 +24,6 @@
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.never;
-import static org.mockito.Mockito.reset;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
index 2cd62889a..0462cbafe 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024 - 2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.server.transport;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
index b04ecb3c4..bf38e68ec 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
@@ -1,10 +1,10 @@
 /*
  * Copyright 2024 - 2025 the original author or authors.
  */
+
 package io.modelcontextprotocol.server.transport;
 
 import java.time.Duration;
-import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.CopyOnWriteArrayList;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
index 5a3928e02..2cf95dc94 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2025 - 2025 the original author or authors.
 */
+
 package io.modelcontextprotocol.server.transport;
 
 import java.io.IOException;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java b/mcp/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java
index ba4e851f9..a0bd568ef 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java
@@ -1,3 +1,7 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
 package io.modelcontextprotocol.spec;
 
 public class ArgumentException {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
index 9da31b38b..30158543d 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
@@ -1,6 +1,7 @@
 /*
  * Copyright 2024-2024 the original author or authors.
  */
+
 package io.modelcontextprotocol.spec;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -26,7 +27,6 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.spec.DefaultJsonSchemaValidator;
 import io.modelcontextprotocol.spec.JsonSchemaValidator.ValidationResponse;
 
 /**
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index fbbb4307e..612222725 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -1,6 +1,7 @@
 /*
 * Copyright 2025 - 2025 the original author or authors.
 */
+
 package io.modelcontextprotocol.spec;
 
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;

From 577952d1ee66713e2fa2e916287d31f72d8d9f93 Mon Sep 17 00:00:00 2001
From: Yanming Zhou 
Date: Thu, 12 Jun 2025 15:29:02 +0800
Subject: [PATCH 036/125] Fix typo

---
 .../java/io/modelcontextprotocol/spec/McpServerSession.java     | 2 +-
 mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index 538023e82..de7c48a4f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -25,7 +25,7 @@
 import reactor.core.publisher.Sinks;
 
 /**
- * Represents a Model Control Protocol (MCP) session on the server side. It manages
+ * Represents a Model Context Protocol (MCP) session on the server side. It manages
  * bidirectional JSON-RPC communication with the client.
  */
 public class McpServerSession implements McpLoggableSession {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
index 42d170db5..3473a4da8 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
@@ -8,7 +8,7 @@
 import reactor.core.publisher.Mono;
 
 /**
- * Represents a Model Control Protocol (MCP) session that handles communication between
+ * Represents a Model Context Protocol (MCP) session that handles communication between
  * clients and the server. This interface provides methods for sending requests and
  * notifications, as well as managing the session lifecycle.
  *

From 5e035ea2555f561ce5e840d5fa07f6aa8f834715 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Mon, 4 Aug 2025 12:07:31 +0100
Subject: [PATCH 037/125] fix: add backward compatibility for MCP servers
 returning older protocol versions

- Add ProtocolVersions interface with version constants
- Change protocolVersion() to protocolVersions() returning List
- Streamable HTTP clients now support both 2024-11-05 and 2025-03-26
- Fixes compatibility with MCP servers that return 2024-11-05 instead of 2025-03-26

Resolves #436
Related to #438

Signed-off-by: Christian Tzolov 
---
 .../WebClientStreamableHttpTransport.java     |  7 +++---
 .../transport/WebFluxSseClientTransport.java  |  8 ++++---
 .../WebFluxSseServerTransportProvider.java    |  6 +++--
 ...FluxStreamableServerTransportProvider.java |  5 ++--
 .../WebMvcSseServerTransportProvider.java     |  6 +++--
 ...bMvcStreamableServerTransportProvider.java |  5 ++--
 .../client/LifecycleInitializer.java          |  3 ++-
 .../client/McpAsyncClient.java                |  6 ++---
 .../HttpClientSseClientTransport.java         |  8 ++++---
 .../HttpClientStreamableHttpTransport.java    |  7 +++---
 .../server/McpAsyncServer.java                |  4 ++--
 .../server/McpStatelessAsyncServer.java       |  2 +-
 ...HttpServletSseServerTransportProvider.java |  6 +++--
 ...vletStreamableServerTransportProvider.java |  5 ++--
 .../StdioServerTransportProvider.java         |  6 +++--
 .../modelcontextprotocol/spec/McpSchema.java  |  2 +-
 .../spec/McpServerTransportProviderBase.java  |  5 ++--
 .../spec/McpStatelessServerTransport.java     |  6 +++--
 .../spec/McpTransport.java                    |  6 +++--
 .../spec/ProtocolVersions.java                | 23 +++++++++++++++++++
 .../MockMcpClientTransport.java               |  4 ++--
 .../McpAsyncClientResponseHandlerTests.java   |  2 +-
 .../client/McpAsyncClientTests.java           |  6 +++--
 .../client/McpClientProtocolVersionTests.java |  8 ++++---
 .../server/McpServerProtocolVersionTests.java |  7 ++++--
 .../spec/McpSchemaTests.java                  |  8 +++----
 26 files changed, 107 insertions(+), 54 deletions(-)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index b7b544660..4758fd2d2 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -34,6 +34,7 @@
 import io.modelcontextprotocol.spec.McpTransportSession;
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.spec.McpTransportStream;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
 import reactor.core.Disposable;
@@ -71,7 +72,7 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(WebClientStreamableHttpTransport.class);
 
-	private static final String MCP_PROTOCOL_VERSION = "2025-03-26";
+	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_03_26;
 
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
@@ -111,8 +112,8 @@ private WebClientStreamableHttpTransport(ObjectMapper objectMapper, WebClient.Bu
 	}
 
 	@Override
-	public String protocolVersion() {
-		return MCP_PROTOCOL_VERSION;
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
 	}
 
 	/**
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
index f122c8fab..75caebef0 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
@@ -5,6 +5,7 @@
 package io.modelcontextprotocol.client.transport;
 
 import java.io.IOException;
+import java.util.List;
 import java.util.function.BiConsumer;
 import java.util.function.Function;
 
@@ -16,6 +17,7 @@
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -65,7 +67,7 @@ public class WebFluxSseClientTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(WebFluxSseClientTransport.class);
 
-	private static final String MCP_PROTOCOL_VERSION = "2024-11-05";
+	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2024_11_05;
 
 	/**
 	 * Event type for JSON-RPC messages received through the SSE connection. The server
@@ -172,8 +174,8 @@ public WebFluxSseClientTransport(WebClient.Builder webClientBuilder, ObjectMappe
 	}
 
 	@Override
-	public String protocolVersion() {
-		return MCP_PROTOCOL_VERSION;
+	public List protocolVersions() {
+		return List.of(MCP_PROTOCOL_VERSION);
 	}
 
 	/**
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index c2c2c2ea6..aaf7bab46 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -6,6 +6,7 @@
 
 import java.io.IOException;
 import java.time.Duration;
+import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
 
 import com.fasterxml.jackson.core.type.TypeReference;
@@ -15,6 +16,7 @@
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
 
@@ -219,8 +221,8 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseU
 	}
 
 	@Override
-	public String protocolVersion() {
-		return "2024-11-05";
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
 	@Override
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index b9111d638..f3f6c2c33 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -14,6 +14,7 @@
 import io.modelcontextprotocol.spec.McpStreamableServerSession;
 import io.modelcontextprotocol.spec.McpStreamableServerTransport;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
@@ -96,8 +97,8 @@ private WebFluxStreamableServerTransportProvider(ObjectMapper objectMapper, Stri
 	}
 
 	@Override
-	public String protocolVersion() {
-		return "2025-03-26";
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
 	}
 
 	@Override
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index a3898006d..ff452ca74 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -6,6 +6,7 @@
 
 import java.io.IOException;
 import java.time.Duration;
+import java.util.List;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
@@ -16,6 +17,7 @@
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
@@ -210,8 +212,8 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUr
 	}
 
 	@Override
-	public String protocolVersion() {
-		return "2024-11-05";
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
 	@Override
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index 4a2117ca4..fa51a0130 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -32,6 +32,7 @@
 import io.modelcontextprotocol.spec.McpStreamableServerSession;
 import io.modelcontextprotocol.spec.McpStreamableServerTransport;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
 import reactor.core.publisher.Flux;
@@ -142,8 +143,8 @@ private WebMvcStreamableServerTransportProvider(ObjectMapper objectMapper, Strin
 	}
 
 	@Override
-	public String protocolVersion() {
-		return "2025-03-26";
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
 	}
 
 	@Override
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
index 4eb94daa5..2e0b51748 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
@@ -290,7 +290,8 @@ public  Mono withIntitialization(String actionName, Function {
 					logger.warn("Failed to initialize", ex);
-					return Mono.error(new McpError("Client failed to initialize " + actionName));
+					return Mono.error(
+							new McpError("Client failed to initialize " + actionName + " due to: " + ex.getMessage()));
 				})
 				.flatMap(operation);
 		});
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 27d9d2e6c..0f2ee19fa 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -272,9 +272,9 @@ public class McpAsyncClient {
 		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_PROGRESS,
 				asyncProgressNotificationHandler(progressConsumersFinal));
 
-		this.initializer = new LifecycleInitializer(clientCapabilities, clientInfo,
-				List.of(transport.protocolVersion()), initializationTimeout, ctx -> new McpClientSession(requestTimeout,
-						transport, requestHandlers, notificationHandlers, con -> con.contextWrite(ctx)));
+		this.initializer = new LifecycleInitializer(clientCapabilities, clientInfo, transport.protocolVersions(),
+				initializationTimeout, ctx -> new McpClientSession(requestTimeout, transport, requestHandlers,
+						notificationHandlers, con -> con.contextWrite(ctx)));
 		this.transport.setExceptionHandler(this.initializer::handleException);
 	}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 62c34fb8f..473f71fbb 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -10,6 +10,7 @@
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.time.Duration;
+import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Consumer;
@@ -25,6 +26,7 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
@@ -62,7 +64,7 @@
  */
 public class HttpClientSseClientTransport implements McpClientTransport {
 
-	private static final String MCP_PROTOCOL_VERSION = "2024-11-05";
+	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2024_11_05;
 
 	private static final String MCP_PROTOCOL_VERSION_HEADER_NAME = "MCP-Protocol-Version";
 
@@ -217,8 +219,8 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 	}
 
 	@Override
-	public String protocolVersion() {
-		return MCP_PROTOCOL_VERSION;
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index dadb09abc..3cfa7359b 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -35,6 +35,7 @@
 import io.modelcontextprotocol.spec.McpTransportSession;
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.spec.McpTransportStream;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
 import reactor.core.Disposable;
@@ -73,7 +74,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(HttpClientStreamableHttpTransport.class);
 
-	private static final String MCP_PROTOCOL_VERSION = "2025-03-26";
+	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_03_26;
 
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
@@ -135,8 +136,8 @@ private HttpClientStreamableHttpTransport(ObjectMapper objectMapper, HttpClient
 	}
 
 	@Override
-	public String protocolVersion() {
-		return MCP_PROTOCOL_VERSION;
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
 	}
 
 	public static Builder builder(String baseUri) {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index 9605fb3f2..5b5e838f3 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -145,7 +145,7 @@ public class McpAsyncServer {
 		Map> requestHandlers = prepareRequestHandlers();
 		Map notificationHandlers = prepareNotificationHandlers(features);
 
-		this.protocolVersions = List.of(mcpTransportProvider.protocolVersion());
+		this.protocolVersions = mcpTransportProvider.protocolVersions();
 
 		mcpTransportProvider.setSessionFactory(transport -> new McpServerSession(UUID.randomUUID().toString(),
 				requestTimeout, transport, this::asyncInitializeRequestHandler, requestHandlers, notificationHandlers));
@@ -170,7 +170,7 @@ public class McpAsyncServer {
 		Map> requestHandlers = prepareRequestHandlers();
 		Map notificationHandlers = prepareNotificationHandlers(features);
 
-		this.protocolVersions = List.of(mcpTransportProvider.protocolVersion());
+		this.protocolVersions = mcpTransportProvider.protocolVersions();
 
 		mcpTransportProvider.setSessionFactory(new DefaultMcpStreamableServerSessionFactory(requestTimeout,
 				this::asyncInitializeRequestHandler, requestHandlers, notificationHandlers));
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 565c53f13..41e0e9588 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -118,7 +118,7 @@ public class McpStatelessAsyncServer {
 			requestHandlers.put(McpSchema.METHOD_COMPLETION_COMPLETE, completionCompleteRequestHandler());
 		}
 
-		this.protocolVersions = List.of(mcpTransport.protocolVersion());
+		this.protocolVersions = new ArrayList<>(mcpTransport.protocolVersions());
 
 		McpStatelessServerHandler handler = new DefaultMcpStatelessServerHandler(requestHandlers, Map.of());
 		mcpTransport.setMcpHandler(handler);
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index 40d293216..ceeea31b1 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -8,6 +8,7 @@
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.time.Duration;
+import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
@@ -20,6 +21,7 @@
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
 import jakarta.servlet.AsyncContext;
@@ -180,8 +182,8 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String b
 	}
 
 	@Override
-	public String protocolVersion() {
-		return "2024-11-05";
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
index 6805bf194..8b95ec607 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
@@ -28,6 +28,7 @@
 import io.modelcontextprotocol.spec.McpStreamableServerSession;
 import io.modelcontextprotocol.spec.McpStreamableServerTransport;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
 import jakarta.servlet.AsyncContext;
@@ -155,8 +156,8 @@ private HttpServletStreamableServerTransportProvider(ObjectMapper objectMapper,
 	}
 
 	@Override
-	public String protocolVersion() {
-		return "2025-03-26";
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
 	}
 
 	@Override
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
index d2943b31d..af602f610 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
@@ -10,6 +10,7 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.List;
 import java.util.concurrent.Executors;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.function.Function;
@@ -22,6 +23,7 @@
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -89,8 +91,8 @@ public StdioServerTransportProvider(ObjectMapper objectMapper, InputStream input
 	}
 
 	@Override
-	public String protocolVersion() {
-		return "2024-11-05";
+	public List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
 	@Override
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index fb4baabfb..af0f55a91 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -45,7 +45,7 @@ private McpSchema() {
 	}
 
 	@Deprecated
-	public static final String LATEST_PROTOCOL_VERSION = "2025-03-26";
+	public static final String LATEST_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_03_26;
 
 	public static final String JSONRPC_VERSION = "2.0";
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
index d1b252a26..acb1ecac6 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.spec;
 
+import java.util.List;
 import java.util.Map;
 
 import reactor.core.publisher.Mono;
@@ -63,8 +64,8 @@ default void close() {
 	 * Returns the protocol version supported by this transport provider.
 	 * @return the protocol version as a string
 	 */
-	default String protocolVersion() {
-		return "2024-11-05";
+	default List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
index 14ed54438..c1234b130 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.spec;
 
+import java.util.List;
+
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
 import reactor.core.publisher.Mono;
 
@@ -26,8 +28,8 @@ default void close() {
 	 */
 	Mono closeGracefully();
 
-	default String protocolVersion() {
-		return "2025-03-26";
+	default List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2025_03_26);
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
index 49c485059..1922548a6 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.spec;
 
+import java.util.List;
+
 import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
 import reactor.core.publisher.Mono;
@@ -77,8 +79,8 @@ default void close() {
 	 */
 	 T unmarshalFrom(Object data, TypeReference typeRef);
 
-	default String protocolVersion() {
-		return "2024-11-05";
+	default List protocolVersions() {
+		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java b/mcp/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
new file mode 100644
index 000000000..d8cb913a5
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
@@ -0,0 +1,23 @@
+package io.modelcontextprotocol.spec;
+
+public interface ProtocolVersions {
+
+	/**
+	 * MCP protocol version for 2024-11-05.
+	 * https://modelcontextprotocol.io/specification/2024-11-05
+	 */
+	String MCP_2024_11_05 = "2024-11-05";
+
+	/**
+	 * MCP protocol version for 2025-03-26.
+	 * https://modelcontextprotocol.io/specification/2025-03-26
+	 */
+	String MCP_2025_03_26 = "2025-03-26";
+
+	/**
+	 * MCP protocol version for 2025-06-18.
+	 * https://modelcontextprotocol.io/specification/2025-06-18
+	 */
+	String MCP_2025_06_18 = "2025-06-18";
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java b/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
index b531d5739..b1113a6d0 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
@@ -45,8 +45,8 @@ public MockMcpClientTransport withProtocolVersion(String protocolVersion) {
 	}
 
 	@Override
-	public String protocolVersion() {
-		return protocolVersion;
+	public List protocolVersions() {
+		return List.of(protocolVersion);
 	}
 
 	public void simulateIncomingMessage(McpSchema.JSONRPCMessage message) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
index 11bd2e4e9..b2fd7fb65 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
@@ -79,7 +79,7 @@ void testSuccessfulInitialization() {
 
 		// Verify initialization result
 		assertThat(result).isNotNull();
-		assertThat(result.protocolVersion()).isEqualTo(transport.protocolVersion());
+		assertThat(result.protocolVersion()).isEqualTo(transport.protocolVersions().get(0));
 		assertThat(result.capabilities()).isEqualTo(serverCapabilities);
 		assertThat(result.serverInfo()).isEqualTo(serverInfo);
 		assertThat(result.instructions()).isEqualTo("Test instructions");
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
index 2c0331f4d..ae33898b7 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
@@ -8,6 +8,8 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.ProtocolVersions;
+
 import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Mono;
 
@@ -24,8 +26,8 @@ class McpAsyncClientTests {
 	public static final McpSchema.ServerCapabilities MOCK_SERVER_CAPABILITIES = McpSchema.ServerCapabilities.builder()
 		.build();
 
-	public static final McpSchema.InitializeResult MOCK_INIT_RESULT = new McpSchema.InitializeResult("2024-11-05",
-			MOCK_SERVER_CAPABILITIES, MOCK_SERVER_INFO, "Test instructions");
+	public static final McpSchema.InitializeResult MOCK_INIT_RESULT = new McpSchema.InitializeResult(
+			ProtocolVersions.MCP_2024_11_05, MOCK_SERVER_CAPABILITIES, MOCK_SERVER_INFO, "Test instructions");
 
 	private static final String CONTEXT_KEY = "context.key";
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
index 2d41fc55f..36216988f 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
@@ -37,18 +37,20 @@ void shouldUseLatestVersionByDefault() {
 		try {
 			Mono initializeResultMono = client.initialize();
 
+			String protocolVersion = transport.protocolVersions().get(transport.protocolVersions().size() - 1);
+
 			StepVerifier.create(initializeResultMono).then(() -> {
 				McpSchema.JSONRPCRequest request = transport.getLastSentMessageAsRequest();
 				assertThat(request.params()).isInstanceOf(McpSchema.InitializeRequest.class);
 				McpSchema.InitializeRequest initRequest = (McpSchema.InitializeRequest) request.params();
-				assertThat(initRequest.protocolVersion()).isEqualTo(transport.protocolVersion());
+				assertThat(initRequest.protocolVersion()).isEqualTo(transport.protocolVersions().get(0));
 
 				transport.simulateIncomingMessage(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
-						new McpSchema.InitializeResult(transport.protocolVersion(), null,
+						new McpSchema.InitializeResult(protocolVersion, null,
 								new McpSchema.Implementation("test-server", "1.0.0"), null),
 						null));
 			}).assertNext(result -> {
-				assertThat(result.protocolVersion()).isEqualTo(transport.protocolVersion());
+				assertThat(result.protocolVersion()).isEqualTo(protocolVersion);
 			}).verifyComplete();
 
 		}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
index 95086ee81..cdd2bacb7 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
@@ -45,7 +45,9 @@ void shouldUseLatestVersionByDefault() {
 		assertThat(jsonResponse.id()).isEqualTo(requestId);
 		assertThat(jsonResponse.result()).isInstanceOf(McpSchema.InitializeResult.class);
 		McpSchema.InitializeResult result = (McpSchema.InitializeResult) jsonResponse.result();
-		assertThat(result.protocolVersion()).isEqualTo(transportProvider.protocolVersion());
+
+		var protocolVersion = transportProvider.protocolVersions().get(transportProvider.protocolVersions().size() - 1);
+		assertThat(result.protocolVersion()).isEqualTo(protocolVersion);
 
 		server.closeGracefully().subscribe();
 	}
@@ -93,7 +95,8 @@ void shouldSuggestLatestVersionForUnsupportedVersion() {
 		assertThat(jsonResponse.id()).isEqualTo(requestId);
 		assertThat(jsonResponse.result()).isInstanceOf(McpSchema.InitializeResult.class);
 		McpSchema.InitializeResult result = (McpSchema.InitializeResult) jsonResponse.result();
-		assertThat(result.protocolVersion()).isEqualTo(transportProvider.protocolVersion());
+		var protocolVersion = transportProvider.protocolVersions().get(transportProvider.protocolVersions().size() - 1);
+		assertThat(result.protocolVersion()).isEqualTo(protocolVersion);
 
 		server.closeGracefully().subscribe();
 	}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index 612222725..a5b2137fd 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -320,8 +320,8 @@ void testInitializeRequest() throws Exception {
 		McpSchema.Implementation clientInfo = new McpSchema.Implementation("test-client", "1.0.0");
 		Map meta = Map.of("metaKey", "metaValue");
 
-		McpSchema.InitializeRequest request = new McpSchema.InitializeRequest("2024-11-05", capabilities, clientInfo,
-				meta);
+		McpSchema.InitializeRequest request = new McpSchema.InitializeRequest(ProtocolVersions.MCP_2024_11_05,
+				capabilities, clientInfo, meta);
 
 		String value = mapper.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
@@ -343,8 +343,8 @@ void testInitializeResult() throws Exception {
 
 		McpSchema.Implementation serverInfo = new McpSchema.Implementation("test-server", "1.0.0");
 
-		McpSchema.InitializeResult result = new McpSchema.InitializeResult("2024-11-05", capabilities, serverInfo,
-				"Server initialized successfully");
+		McpSchema.InitializeResult result = new McpSchema.InitializeResult(ProtocolVersions.MCP_2024_11_05,
+				capabilities, serverInfo, "Server initialized successfully");
 
 		String value = mapper.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)

From 3a95f757f32c758f84332d9684dd7a81b7d630b4 Mon Sep 17 00:00:00 2001
From: Yanming Zhou 
Date: Tue, 5 Aug 2025 09:36:24 +0800
Subject: [PATCH 038/125] Remove duplicate header MCP_PROTOCOL_VERSION

Signed-off-by: Yanming Zhou 
---
 .../client/transport/WebClientStreamableHttpTransport.java   | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 4758fd2d2..6d8e82f51 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -143,11 +143,8 @@ private DefaultMcpTransportSession createTransportSession() {
 		Function> onClose = sessionId -> sessionId == null ? Mono.empty()
 				: webClient.delete()
 					.uri(this.endpoint)
+					.header(HttpHeaders.MCP_SESSION_ID, sessionId)
 					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
-					.headers(httpHeaders -> {
-						httpHeaders.add(HttpHeaders.MCP_SESSION_ID, sessionId);
-						httpHeaders.add(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION);
-					})
 					.retrieve()
 					.toBodilessEntity()
 					.onErrorComplete(e -> {

From 5aba8a0e8f6979f7b718f9b97e3c783e842a3d32 Mon Sep 17 00:00:00 2001
From: codezkk <52305579+codezkk@users.noreply.github.com>
Date: Fri, 1 Aug 2025 16:01:24 +0800
Subject: [PATCH 039/125] fix: handle empty JSON responses in
 ResponseSubscribers

- Remove length check in hookOnComplete() to always emit AggregateResponseEvent
- Ensures proper completion handling regardless of response content length
- Add test for empty application/json responses with 200 OK status
---
 .../client/transport/ResponseSubscribers.java |  7 +-
 ...bleHttpTransportEmptyJsonResponseTest.java | 92 +++++++++++++++++++
 2 files changed, 95 insertions(+), 4 deletions(-)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
index 1ac559d78..2cc381e1b 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
@@ -238,10 +238,9 @@ protected void hookOnNext(String line) {
 
 		@Override
 		protected void hookOnComplete() {
-			if (this.eventBuilder.length() > 0) {
-				String data = this.eventBuilder.toString();
-				this.sink.next(new AggregateResponseEvent(responseInfo, data));
-			}
+			String data = this.eventBuilder.toString();
+			this.sink.next(new AggregateResponseEvent(responseInfo, data));
+
 			this.sink.complete();
 		}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
new file mode 100644
index 000000000..f047015d7
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
@@ -0,0 +1,92 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.net.URI;
+import java.net.URISyntaxException;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+
+import com.sun.net.httpserver.HttpServer;
+
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.ProtocolVersions;
+import reactor.test.StepVerifier;
+
+/**
+ * Handles emplty application/json response with 200 OK status code.
+ *
+ * @author codezkk
+ */
+public class HttpClientStreamableHttpTransportEmptyJsonResponseTest {
+
+	static int PORT = TomcatTestUtil.findAvailablePort();
+
+	static String host = "http://localhost:" + PORT;
+
+	static HttpServer server;
+
+	@BeforeAll
+	static void startContainer() throws IOException {
+
+		server = HttpServer.create(new InetSocketAddress(PORT), 0);
+
+		// Empty, 200 OK response for the /mcp endpoint
+		server.createContext("/mcp", exchange -> {
+			exchange.getResponseHeaders().set("Content-Type", "application/json");
+			exchange.sendResponseHeaders(200, 0);
+			exchange.close();
+		});
+
+		server.setExecutor(null);
+		server.start();
+	}
+
+	@AfterAll
+	static void stopContainer() {
+		server.stop(1);
+	}
+
+	/**
+	 * Regardless of the response (even if the response is null and the content-type is
+	 * present), notify should handle it correctly.
+	 */
+	@Test
+	@Timeout(3)
+	void testNotificationInitialized() throws URISyntaxException {
+
+		var uri = new URI(host + "/mcp");
+		var mockRequestCustomizer = mock(SyncHttpRequestCustomizer.class);
+		var transport = HttpClientStreamableHttpTransport.builder(host)
+			.httpRequestCustomizer(mockRequestCustomizer)
+			.build();
+
+		var initializeRequest = new McpSchema.InitializeRequest(ProtocolVersions.MCP_2025_03_26,
+				McpSchema.ClientCapabilities.builder().roots(true).build(),
+				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
+				"test-id", initializeRequest);
+
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// Verify the customizer was called
+		verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("GET"), eq(uri), eq(
+				"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
+
+	}
+
+}

From 7f37ddc4d76625e53201e1e6aa58c2bcd99ed034 Mon Sep 17 00:00:00 2001
From: Yanming Zhou 
Date: Tue, 5 Aug 2025 09:51:14 +0800
Subject: [PATCH 040/125] Use `Last-Event-ID` instead of `last-event-id`

see https://html.spec.whatwg.org/multipage/server-sent-events.html#the-last-event-id-header

Signed-off-by: Yanming Zhou 
---
 mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
index 7c0aeacc4..65b80957c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
@@ -19,7 +19,7 @@ public interface HttpHeaders {
 	/**
 	 * Identifies events within an SSE Stream.
 	 */
-	String LAST_EVENT_ID = "last-event-id";
+	String LAST_EVENT_ID = "Last-Event-ID";
 
 	/**
 	 * Identifies the MCP protocol version.

From 110a8d1940ca2edf45524332dcc84b606e52d879 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Wed, 6 Aug 2025 08:34:30 +0100
Subject: [PATCH 041/125] refactor: downgrade unhandled notification logging
 from error to warn

- Change logger.error() to logger.warn() for unhandled notification methods
- Log full notification object instead of just method name for better context
- Affects McpClientSession, McpServerSession, and McpStreamableServerSession

Signed-off-by: Christian Tzolov 
---
 .../java/io/modelcontextprotocol/spec/McpClientSession.java     | 2 +-
 .../java/io/modelcontextprotocol/spec/McpServerSession.java     | 2 +-
 .../modelcontextprotocol/spec/McpStreamableServerSession.java   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
index cc7d2abf8..f7db3d7aa 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
@@ -221,7 +221,7 @@ private Mono handleIncomingNotification(McpSchema.JSONRPCNotification noti
 		return Mono.defer(() -> {
 			var handler = notificationHandlers.get(notification.method());
 			if (handler == null) {
-				logger.error("No handler registered for notification method: {}", notification.method());
+				logger.warn("No handler registered for notification method: {}", notification);
 				return Mono.empty();
 			}
 			return handler.handle(notification.params());
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index de7c48a4f..62985dc17 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -294,7 +294,7 @@ private Mono handleIncomingNotification(McpSchema.JSONRPCNotification noti
 
 			var handler = notificationHandlers.get(notification.method());
 			if (handler == null) {
-				logger.error("No handler registered for notification method: {}", notification.method());
+				logger.warn("No handler registered for notification method: {}", notification);
 				return Mono.empty();
 			}
 			return this.exchangeSink.asMono().flatMap(exchange -> handler.handle(exchange, notification.params()));
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
index 3eec75c09..ef7967c1e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -197,7 +197,7 @@ public Mono accept(McpSchema.JSONRPCNotification notification) {
 			McpTransportContext transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
 			McpNotificationHandler notificationHandler = this.notificationHandlers.get(notification.method());
 			if (notificationHandler == null) {
-				logger.error("No handler registered for notification method: {}", notification.method());
+				logger.warn("No handler registered for notification method: {}", notification);
 				return Mono.empty();
 			}
 			McpLoggableSession listeningStream = this.listeningStreamRef.get();

From 032716546c72cc9a7d66c367c75aa7ad284b530e Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Thu, 7 Aug 2025 09:32:40 +0200
Subject: [PATCH 042/125] Fix httpRequestCustomizer usage in
 HttpClientStreamableHttpTransport

- Closes #458

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../client/transport/HttpClientStreamableHttpTransport.java   | 2 +-
 ...ttpClientStreamableHttpTransportEmptyJsonResponseTest.java | 2 +-
 .../transport/HttpClientStreamableHttpTransportTest.java      | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index 3cfa7359b..a9e5897b9 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -400,7 +400,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 					.header("Cache-Control", "no-cache")
 					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
-				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, jsonBody));
+				return Mono.from(this.httpRequestCustomizer.customize(builder, "POST", uri, jsonBody));
 			}).flatMapMany(requestBuilder -> Flux.create(responseEventSink -> {
 
 				// Create the async request with proper body subscriber selection
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
index f047015d7..8b3668671 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
@@ -84,7 +84,7 @@ void testNotificationInitialized() throws URISyntaxException {
 		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
 
 		// Verify the customizer was called
-		verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("GET"), eq(uri), eq(
+		verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
 				"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
 
 	}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index 479468f63..d645bb0b3 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -80,7 +80,7 @@ void testRequestCustomizer() throws URISyntaxException {
 			StepVerifier.create(t.sendMessage(testMessage)).verifyComplete();
 
 			// Verify the customizer was called
-			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("GET"), eq(uri), eq(
+			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
 					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
 		});
 	}
@@ -107,7 +107,7 @@ void testAsyncRequestCustomizer() throws URISyntaxException {
 			StepVerifier.create(t.sendMessage(testMessage)).verifyComplete();
 
 			// Verify the customizer was called
-			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("GET"), eq(uri), eq(
+			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
 					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
 		});
 	}

From 4532b614e4d9431b8290f87dd2f20f2e5dd0f962 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 7 Aug 2025 10:03:41 +0100
Subject: [PATCH 043/125] feat: handle SSE comment messages

- Add support for ignoring SSE comment lines that start with ':'
- Add debug logging for comment line processing

Resolves #443

Signed-off-by: Christian Tzolov 
---
 .../client/transport/ResponseSubscribers.java            | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
index 2cc381e1b..4d9bdea5d 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
@@ -12,6 +12,8 @@
 
 import org.reactivestreams.FlowAdapters;
 import org.reactivestreams.Subscription;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import io.modelcontextprotocol.spec.McpError;
 import reactor.core.publisher.BaseSubscriber;
@@ -31,6 +33,8 @@
  */
 class ResponseSubscribers {
 
+	private static final Logger logger = LoggerFactory.getLogger(ResponseSubscribers.class);
+
 	record SseEvent(String id, String event, String data) {
 	}
 
@@ -167,6 +171,11 @@ else if (line.startsWith("event:")) {
 						this.currentEventType.set(matcher.group(1).trim());
 					}
 				}
+				else if (line.startsWith(":")) {
+					// Ignore comment lines starting with ":"
+					// This is a no-op, just to skip comments
+					logger.debug("Ignoring comment line: {}", line);
+				}
 				else {
 					// If the response is not successful, emit an error
 					// TODO: This should be a McpTransportError

From a14ef425d60a31762f5fdc4e176fc1f300251641 Mon Sep 17 00:00:00 2001
From: Jordan Zimmerman 
Date: Thu, 7 Aug 2025 08:26:07 +0100
Subject: [PATCH 044/125] If a handler throws McpError, use its values for the
 RPC error

Handlers should be able to throw RPC errors and `McpError` is the
right exception for that.

Improve `DefaultMcpStatelessServerHandler` error handler to check if the
exception is `McpError` and, if so, use it to build the RPC error
result instead of re-writing as `INTERNAL_ERROR`.
---
 .../DefaultMcpStatelessServerHandler.java     | 14 ++-
 .../HttpServletStatelessIntegrationTests.java | 93 ++++++++++++++-----
 2 files changed, 82 insertions(+), 25 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
index 9a1f6e84e..2df3514b6 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
@@ -35,9 +35,17 @@ public Mono handleRequest(McpTransportContext transpo
 		}
 		return requestHandler.handle(transportContext, request.params())
 			.map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), result, null))
-			.onErrorResume(t -> Mono.just(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null,
-					new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR, t.getMessage(),
-							null))));
+			.onErrorResume(t -> {
+				McpSchema.JSONRPCResponse.JSONRPCError error;
+				if (t instanceof McpError mcpError && mcpError.getJsonRpcError() != null) {
+					error = mcpError.getJsonRpcError();
+				}
+				else {
+					error = new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
+							t.getMessage(), null);
+				}
+				return Mono.just(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null, error));
+			});
 	}
 
 	@Override
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index 00942226f..4c3f22d76 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -4,33 +4,13 @@
 
 package io.modelcontextprotocol.server;
 
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.awaitility.Awaitility.await;
-
-import java.time.Duration;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.BiFunction;
-
-import org.apache.catalina.LifecycleException;
-import org.apache.catalina.LifecycleState;
-import org.apache.catalina.startup.Tomcat;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
-import org.springframework.web.client.RestClient;
-
 import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.HttpHeaders;
+import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
@@ -41,7 +21,33 @@
 import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import net.javacrumbs.jsonunit.core.Option;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.web.client.RestClient;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
+
+import static io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport.APPLICATION_JSON;
+import static io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport.TEXT_EVENT_STREAM;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
 
 class HttpServletStatelessIntegrationTests {
 
@@ -460,6 +466,49 @@ void testStructuredOutputRuntimeToolAddition(String clientType) {
 		mcpServer.close();
 	}
 
+	@Test
+	void testThrownMcpError() throws Exception {
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.build();
+
+		Tool testTool = Tool.builder().name("test").description("test").build();
+
+		McpStatelessServerFeatures.SyncToolSpecification toolSpec = new McpStatelessServerFeatures.SyncToolSpecification(
+				testTool, (transportContext, request) -> {
+					throw new McpError(new McpSchema.JSONRPCResponse.JSONRPCError(12345, "testing", Map.of("a", "b")));
+				});
+
+		mcpServer.addTool(toolSpec);
+
+		McpSchema.CallToolRequest callToolRequest = new McpSchema.CallToolRequest("test", Map.of());
+		McpSchema.JSONRPCRequest jsonrpcRequest = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION,
+				McpSchema.METHOD_TOOLS_CALL, "test", callToolRequest);
+
+		MockHttpServletRequest request = new MockHttpServletRequest("POST", CUSTOM_MESSAGE_ENDPOINT);
+		MockHttpServletResponse response = new MockHttpServletResponse();
+
+		byte[] content = new ObjectMapper().writeValueAsBytes(jsonrpcRequest);
+		request.setContent(content);
+		request.addHeader("Content-Type", "application/json");
+		request.addHeader("Content-Length", Integer.toString(content.length));
+		request.addHeader("Content-Length", Integer.toString(content.length));
+		request.addHeader("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM);
+		request.addHeader("Content-Type", APPLICATION_JSON);
+		request.addHeader("Cache-Control", "no-cache");
+		request.addHeader(HttpHeaders.PROTOCOL_VERSION, ProtocolVersions.MCP_2025_03_26);
+		mcpStatelessServerTransport.service(request, response);
+
+		McpSchema.JSONRPCResponse jsonrpcResponse = new ObjectMapper().readValue(response.getContentAsByteArray(),
+				McpSchema.JSONRPCResponse.class);
+
+		assertThat(jsonrpcResponse.error())
+			.isEqualTo(new McpSchema.JSONRPCResponse.JSONRPCError(12345, "testing", Map.of("a", "b")));
+
+		mcpServer.close();
+	}
+
 	private double evaluateExpression(String expression) {
 		// Simple expression evaluator for testing
 		return switch (expression) {

From 1edd1b64db96986fb6ca7fe7c8371398bab5b068 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Fri, 8 Aug 2025 09:36:31 +0100
Subject: [PATCH 045/125] feat: Add builder pattern for McpError and mutate
 method for capabilities

- Add builder pattern to McpError for structured error creation with validation
- Deprecate McpError(Object) constructor in favor of builder approach
- Add mutate() method to server capabilities for creating modified copies

Signed-off-by: Christian Tzolov 
---
 .../modelcontextprotocol/spec/McpError.java   | 35 +++++++++++++++++++
 .../modelcontextprotocol/spec/McpSchema.java  | 15 ++++++++
 2 files changed, 50 insertions(+)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java
index 7193237bb..6172d8637 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java
@@ -5,6 +5,7 @@
 package io.modelcontextprotocol.spec;
 
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse.JSONRPCError;
+import io.modelcontextprotocol.util.Assert;
 
 public class McpError extends RuntimeException {
 
@@ -15,6 +16,7 @@ public McpError(JSONRPCError jsonRpcError) {
 		this.jsonRpcError = jsonRpcError;
 	}
 
+	@Deprecated
 	public McpError(Object error) {
 		super(error.toString());
 	}
@@ -23,4 +25,37 @@ public JSONRPCError getJsonRpcError() {
 		return jsonRpcError;
 	}
 
+	public static Builder builder(int errorCode) {
+		return new Builder(errorCode);
+	}
+
+	public static class Builder {
+
+		private final int code;
+
+		private String message;
+
+		private Object data;
+
+		private Builder(int code) {
+			this.code = code;
+		}
+
+		public Builder message(String message) {
+			this.message = message;
+			return this;
+		}
+
+		public Builder data(Object data) {
+			this.data = data;
+			return this;
+		}
+
+		public McpError build() {
+			Assert.hasText(message, "message must not be empty");
+			return new McpError(new JSONRPCError(code, message, data));
+		}
+
+	}
+
 }
\ No newline at end of file
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index af0f55a91..bd8a01555 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -523,6 +523,21 @@ public record ResourceCapabilities(@JsonProperty("subscribe") Boolean subscribe,
 		public record ToolCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
 		}
 
+		/**
+		 * Create a mutated copy of this object with the specified changes.
+		 * @return A new Builder instance with the same values as this object.
+		 */
+		public Builder mutate() {
+			var builder = new Builder();
+			builder.completions = this.completions;
+			builder.experimental = this.experimental;
+			builder.logging = this.logging;
+			builder.prompts = this.prompts;
+			builder.resources = this.resources;
+			builder.tools = this.tools;
+			return builder;
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}

From cbfdb14e4070b79d7b85fb369b79ab01fb535183 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Fri, 8 Aug 2025 21:31:29 +0200
Subject: [PATCH 046/125] refactor: extract common integration test logic into
 abstract base classes (#473)

refactor: extract common integration test logic into abstract base classes

- Move duplicated test methods from WebFlux and WebMvc integration test classes to abstract base classes
- WebFluxSseIntegrationTests, WebFluxStreamableIntegrationTests now extend AbstractMcpClientServerIntegrationTests
- WebFluxStatelessIntegrationTests, WebMvcStatelessIntegrationTests now extend AbstractStatelessIntegrationTests
- Each concrete test class now only implements transport-specific setup methods (prepareClients, prepareAsyncServerBuilder, prepareSyncServerBuilder)
- Eliminates ~1300+ lines of duplicated test code across multiple files
- Improves maintainability by centralizing test logic in reusable base classes
- Updates WebMvcSseServerTransportProvider to use builder pattern
- Adds new HttpServletSseIntegrationTests extending AbstractMcpClientServerIntegrationTests
  - Removes HttpServletSseServerTransportProviderIntegrationTests
- Standardizes timeout configurations and client setup across all integration tests

Signed-off-by: Christian Tzolov 
---
 .../WebFluxSseIntegrationTests.java           | 1463 +---------------
 .../WebFluxStatelessIntegrationTests.java     |  455 +----
 .../WebFluxStreamableIntegrationTests.java    | 1484 +----------------
 .../server/WebMvcSseIntegrationTests.java     |    9 +-
 .../WebMvcStatelessIntegrationTests.java      |   89 +-
 .../WebMvcStreamableIntegrationTests.java     |   34 +-
 ...stractMcpClientServerIntegrationTests.java |  281 +++-
 ...stractMcpClientServerIntegrationTests.java |  277 ++-
 .../HttpServletSseIntegrationTests.java       |   93 ++
 ...HttpServletStreamableIntegrationTests.java |    2 +-
 ...rverTransportProviderIntegrationTests.java | 1390 ---------------
 11 files changed, 792 insertions(+), 4785 deletions(-)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
 delete mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java

diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index 8ce714f94..a1f1a8947 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -4,33 +4,12 @@
 
 package io.modelcontextprotocol;
 
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.assertj.core.api.Assertions.assertWith;
-import static org.awaitility.Awaitility.await;
-import static org.mockito.Mockito.mock;
-
 import java.time.Duration;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.CopyOnWriteArrayList;
-import java.util.concurrent.CountDownLatch;
-import java.util.concurrent.TimeUnit;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.BiFunction;
-import java.util.function.Function;
-import java.util.stream.Collectors;
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
-import org.springframework.web.client.RestClient;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.server.RouterFunctions;
 
@@ -40,36 +19,14 @@
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
 import io.modelcontextprotocol.server.McpServer;
-import io.modelcontextprotocol.server.McpServerFeatures;
-import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.SingleSessionSyncSpecification;
 import io.modelcontextprotocol.server.TestUtil;
 import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
-import io.modelcontextprotocol.spec.McpError;
-import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
-import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
-import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
-import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
-import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
-import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
-import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
-import io.modelcontextprotocol.spec.McpSchema.Prompt;
-import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
-import io.modelcontextprotocol.spec.McpSchema.PromptReference;
-import io.modelcontextprotocol.spec.McpSchema.Role;
-import io.modelcontextprotocol.spec.McpSchema.Root;
-import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.Tool;
-import net.javacrumbs.jsonunit.core.Option;
-import reactor.core.publisher.Mono;
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
-import reactor.test.StepVerifier;
 
-class WebFluxSseIntegrationTests {
+class WebFluxSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
 
@@ -81,1413 +38,55 @@ class WebFluxSseIntegrationTests {
 
 	private WebFluxSseServerTransportProvider mcpServerTransportProvider;
 
-	ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
-
-	@BeforeEach
-	public void before() {
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
 
-		this.mcpServerTransportProvider = new WebFluxSseServerTransportProvider.Builder()
-			.objectMapper(new ObjectMapper())
-			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
-			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
-			.build();
-
-		HttpHandler httpHandler = RouterFunctions.toHttpHandler(mcpServerTransportProvider.getRouterFunction());
-		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
-		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT)
+						.sseEndpoint(CUSTOM_SSE_ENDPOINT)
+						.build()).requestTimeout(Duration.ofHours(10)));
 
-		clientBuilders.put("httpclient",
-				McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT)
-					.sseEndpoint(CUSTOM_SSE_ENDPOINT)
-					.build()));
 		clientBuilders.put("webflux",
 				McpClient
 					.sync(WebFluxSseClientTransport.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
 						.sseEndpoint(CUSTOM_SSE_ENDPOINT)
-						.build()));
-
-	}
-
-	@AfterEach
-	public void after() {
-		if (httpServer != null) {
-			httpServer.disposeNow();
-		}
-	}
-
-	// ---------------------------------------
-	// Sampling Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageWithoutSamplingCapabilities(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> exchange.createMessage(mock(CreateMessageRequest.class))
-				.thenReturn(mock(CallToolResult.class)))
-			.build();
-
-		var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build();
-
-		try (var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
-			.build();) {
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with sampling capabilities");
-			}
-		}
-		server.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		AtomicReference samplingResult = new AtomicReference<>();
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
 						.build())
-					.build();
-
-				return exchange.createMessage(createMessageRequest)
-					.doOnNext(samplingResult::set)
-					.thenReturn(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-
-			assertWith(samplingResult.get(), result -> {
-				assertThat(result).isNotNull();
-				assertThat(result.role()).isEqualTo(Role.USER);
-				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-				assertThat(result.model()).isEqualTo("MockModelName");
-				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-			});
-		}
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws InterruptedException {
-
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		AtomicReference samplingResult = new AtomicReference<>();
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				return exchange.createMessage(craeteMessageRequest)
-					.doOnNext(samplingResult::set)
-					.thenReturn(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.requestTimeout(Duration.ofSeconds(4))
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-
-			assertWith(samplingResult.get(), result -> {
-				assertThat(result).isNotNull();
-				assertThat(result.role()).isEqualTo(Role.USER);
-				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-				assertThat(result.model()).isEqualTo("MockModelName");
-				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-			});
-		}
-
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageWithRequestTimeoutFail(String clientType) throws InterruptedException {
-
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.build();
-
-				return exchange.createMessage(craeteMessageRequest).thenReturn(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.requestTimeout(Duration.ofSeconds(1))
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}).withMessageContaining("within 1000ms");
-
-		}
-
-		mcpServer.closeGracefully().block();
-	}
-
-	// ---------------------------------------
-	// Elicitation Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.createElicitation(mock(ElicitRequest.class)).block();
-
-				return Mono.just(mock(CallToolResult.class));
-			})
-			.build();
-
-		var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build();
-
-		try (
-				// Create client without elicitation capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with elicitation capabilities");
-			}
-		}
-		server.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
-
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(3))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationWithRequestTimeoutFail(String clientType) {
-
-		var latch = new CountDownLatch(1);
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-
-			try {
-				if (!latch.await(2, TimeUnit.SECONDS)) {
-					throw new RuntimeException("Timeout waiting for elicitation processing");
-				}
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1)) // 1 second.
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("within 1000ms");
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	// ---------------------------------------
-	// Roots Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsSuccess(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		List roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-
-			// Remove a root
-			mcpClient.removeRoot(roots.get(0).uri());
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
-			});
-
-			// Add a new root
-			var root3 = new Root("uri3://", "root3");
-			mcpClient.addRoot(root3);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsWithoutCapability(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.listRoots(); // try to list roots
-
-				return mock(CallToolResult.class);
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider).rootsChangeHandler((exchange, rootsUpdate) -> {
-		}).tools(tool).build();
-
-		// Create client without roots capability
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().build()).build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			// Attempt to list roots should fail
-			try {
-				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
-			}
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsNotificationWithEmptyRootsList(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(List.of()) // Empty roots list
-			.build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsWithMultipleHandlers(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
+					.requestTimeout(Duration.ofHours(10)));
 
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef1 = new AtomicReference<>();
-		AtomicReference> rootsRef2 = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef1.set(rootsUpdate))
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef2.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef1.get()).containsAll(roots);
-				assertThat(rootsRef2.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsServerCloseWithActiveSubscription(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Tools Tests
-	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-			"$schema": "http://json-schema.org/draft-07/schema#",
-			"type": "object",
-			"properties": {}
-			}
-			""";
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testToolCallSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testToolListChangeHandlingSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
-			// perform a blocking call to a remote service
-			String response = RestClient.create()
-				.get()
-				.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-				.retrieve()
-				.body(String.class);
-			assertThat(response).isNotBlank();
-			rootsRef.set(toolsUpdate);
-		}).build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			mcpServer.notifyToolsListChanged();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
-			});
-
-			// Remove a tool
-			mcpServer.removeTool("tool1");
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-
-			// Add a new tool
-			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
-				.tool(new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema))
-				.callHandler((exchange, request) -> callResponse)
-				.build();
-
-			mcpServer.addTool(tool2);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testInitialize(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider).build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Logging Tests
-	// ---------------------------------------
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testLoggingNotification(String clientType) throws InterruptedException {
-		int expectedNotificationsCount = 3;
-		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
-		// Create a list to store received logging notifications
-		List receivedNotifications = new CopyOnWriteArrayList<>();
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create server with a tool that sends logging notifications
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				// Create and send notifications with different levels
-
-			//@formatter:off
-					return exchange // This should be filtered out (DEBUG < NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.DEBUG)
-								.logger("test-logger")
-								.data("Debug message")
-								.build())
-					.then(exchange // This should be sent (NOTICE >= NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.NOTICE)
-								.logger("test-logger")
-								.data("Notice message")
-								.build()))
-					.then(exchange // This should be sent (ERROR > NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-							.level(McpSchema.LoggingLevel.ERROR)
-							.logger("test-logger")
-							.data("Error message")
-							.build()))
-					.then(exchange // This should be filtered out (INFO < NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.INFO)
-								.logger("test-logger")
-								.data("Another info message")
-								.build()))
-					.then(exchange // This should be sent (ERROR >= NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.ERROR)
-								.logger("test-logger")
-								.data("Another error message")
-								.build()))
-					.thenReturn(new CallToolResult("Logging test completed", false));
-					//@formatter:on
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (
-				// Create client with logging notification handler
-				var mcpClient = clientBuilder.loggingConsumer(notification -> {
-					receivedNotifications.add(notification);
-					latch.countDown();
-				}).build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Set minimum logging level to NOTICE
-			mcpClient.setLoggingLevel(McpSchema.LoggingLevel.NOTICE);
-
-			// Call the tool that sends logging notifications
-			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Logging test completed");
-
-			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
-
-			// Should have received 3 notifications (1 NOTICE and 2 ERROR)
-			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
-
-			Map notificationMap = receivedNotifications.stream()
-				.collect(Collectors.toMap(n -> n.data(), n -> n));
-
-			// First notification should be NOTICE level
-			assertThat(notificationMap.get("Notice message").level()).isEqualTo(McpSchema.LoggingLevel.NOTICE);
-			assertThat(notificationMap.get("Notice message").logger()).isEqualTo("test-logger");
-			assertThat(notificationMap.get("Notice message").data()).isEqualTo("Notice message");
-
-			// Second notification should be ERROR level
-			assertThat(notificationMap.get("Error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
-			assertThat(notificationMap.get("Error message").logger()).isEqualTo("test-logger");
-			assertThat(notificationMap.get("Error message").data()).isEqualTo("Error message");
-
-			// Third notification should be ERROR level
-			assertThat(notificationMap.get("Another error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
-			assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
-			assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
-		}
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Progress Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testProgressNotification(String clientType) throws InterruptedException {
-		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
-											// token
-		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
-		// Create a list to store received logging notifications
-		List receivedNotifications = new CopyOnWriteArrayList<>();
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create server with a tool that sends logging notifications
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(McpSchema.Tool.builder()
-				.name("progress-test")
-				.description("Test progress notifications")
-				.inputSchema(emptyJsonSchema)
-				.build())
-			.callHandler((exchange, request) -> {
-
-				// Create and send notifications
-				var progressToken = (String) request.meta().get("progressToken");
-
-				return exchange
-					.progressNotification(
-							new McpSchema.ProgressNotification(progressToken, 0.0, 1.0, "Processing started"))
-					.then(exchange.progressNotification(
-							new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Processing data")))
-					.then(// Send a progress notification with another progress value
-							// should
-							exchange.progressNotification(new McpSchema.ProgressNotification("another-progress-token",
-									0.0, 1.0, "Another processing started")))
-					.then(exchange.progressNotification(
-							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
-					.thenReturn(new CallToolResult(("Progress test completed"), false));
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (
-				// Create client with progress notification handler
-				var mcpClient = clientBuilder.progressConsumer(notification -> {
-					receivedNotifications.add(notification);
-					latch.countDown();
-				}).build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call the tool that sends progress notifications
-			McpSchema.CallToolRequest callToolRequest = McpSchema.CallToolRequest.builder()
-				.name("progress-test")
-				.meta(Map.of("progressToken", "test-progress-token"))
-				.build();
-			CallToolResult result = mcpClient.callTool(callToolRequest);
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
-
-			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
-
-			// Should have received 3 notifications
-			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
-
-			Map notificationMap = receivedNotifications.stream()
-				.collect(Collectors.toMap(n -> n.message(), n -> n));
-
-			// First notification should be 0.0/1.0 progress
-			assertThat(notificationMap.get("Processing started").progressToken()).isEqualTo("test-progress-token");
-			assertThat(notificationMap.get("Processing started").progress()).isEqualTo(0.0);
-			assertThat(notificationMap.get("Processing started").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing started").message()).isEqualTo("Processing started");
-
-			// Second notification should be 0.5/1.0 progress
-			assertThat(notificationMap.get("Processing data").progressToken()).isEqualTo("test-progress-token");
-			assertThat(notificationMap.get("Processing data").progress()).isEqualTo(0.5);
-			assertThat(notificationMap.get("Processing data").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing data").message()).isEqualTo("Processing data");
-
-			// Third notification should be another progress token with 0.0/1.0 progress
-			assertThat(notificationMap.get("Another processing started").progressToken())
-				.isEqualTo("another-progress-token");
-			assertThat(notificationMap.get("Another processing started").progress()).isEqualTo(0.0);
-			assertThat(notificationMap.get("Another processing started").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Another processing started").message())
-				.isEqualTo("Another processing started");
-
-			// Fourth notification should be 1.0/1.0 progress
-			assertThat(notificationMap.get("Processing completed").progressToken()).isEqualTo("test-progress-token");
-			assertThat(notificationMap.get("Processing completed").progress()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing completed").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
-		}
-		finally {
-			mcpServer.close();
-		}
 	}
 
-	// ---------------------------------------
-	// Completion Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : Completion call")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var expectedValues = List.of("python", "pytorch", "pyside");
-		var completionResponse = new McpSchema.CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
-				true // hasMore
-		));
-
-		AtomicReference samplingRequest = new AtomicReference<>();
-		BiFunction completionHandler = (mcpSyncServerExchange,
-				request) -> {
-			samplingRequest.set(request);
-			return completionResponse;
-		};
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().completions().build())
-			.prompts(new McpServerFeatures.SyncPromptSpecification(
-					new Prompt("code_review", "Code review", "this is code review prompt",
-							List.of(new PromptArgument("language", "Language", "string", false))),
-					(mcpSyncServerExchange, getPromptRequest) -> null))
-			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CompleteRequest request = new CompleteRequest(
-					new PromptReference("ref/prompt", "code_review", "Code review"),
-					new CompleteRequest.CompleteArgument("language", "py"));
-
-			CompleteResult result = mcpClient.completeCompletion(request);
-
-			assertThat(result).isNotNull();
-
-			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
-			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
-			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
-		}
-
-		mcpServer.close();
+	@Override
+	protected AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(mcpServerTransportProvider);
 	}
 
-	// ---------------------------------------
-	// Ping Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testPingSuccess(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create server with a tool that uses ping functionality
-		AtomicReference executionOrder = new AtomicReference<>("");
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("ping-async-test", "Test ping async behavior", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				executionOrder.set(executionOrder.get() + "1");
-
-				// Test async ping behavior
-				return exchange.ping().doOnNext(result -> {
-
-					assertThat(result).isNotNull();
-					// Ping should return an empty object or map
-					assertThat(result).isInstanceOf(Map.class);
-
-					executionOrder.set(executionOrder.get() + "2");
-					assertThat(result).isNotNull();
-				}).then(Mono.fromCallable(() -> {
-					executionOrder.set(executionOrder.get() + "3");
-					return new CallToolResult("Async ping test completed", false);
-				}));
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call the tool that tests ping async behavior
-			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("ping-async-test", Map.of()));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Async ping test completed");
-
-			// Verify execution order
-			assertThat(executionOrder.get()).isEqualTo("123");
-		}
-
-		mcpServer.closeGracefully().block();
+	@Override
+	protected SingleSessionSyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(mcpServerTransportProvider);
 	}
 
-	// ---------------------------------------
-	// Tool Structured Output Schema Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputValidationSuccess(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of(
-				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
-						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
-				"required", List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					String expression = (String) request.getOrDefault("expression", "2 + 3");
-					double result = evaluateExpression(expression);
-					return CallToolResult.builder()
-						.structuredContent(
-								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Verify tool is listed with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call tool with valid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputValidationFailure(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
-				List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return invalid structured output. Result should be number, missing
-					// operation
-					return CallToolResult.builder()
-						.addTextContent("Invalid calculation")
-						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool with invalid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).contains("Validation failed");
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputMissingStructuredContent(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return result without structured content but tool has output schema
-					return CallToolResult.builder().addTextContent("Calculation completed").build();
-				});
+	@BeforeEach
+	public void before() {
 
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
+		this.mcpServerTransportProvider = new WebFluxSseServerTransportProvider.Builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
+			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
 			.build();
 
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool that should return structured content but doesn't
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).isEqualTo(
-					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
-		}
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(mcpServerTransportProvider.getRouterFunction());
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
 
-		mcpServer.close();
+		prepareClients(PORT, null);
 	}
 
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputRuntimeToolAddition(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Start server without tools
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Initially no tools
-			assertThat(mcpClient.listTools().tools()).isEmpty();
-
-			// Add tool with output schema at runtime
-			Map outputSchema = Map.of("type", "object", "properties",
-					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
-					List.of("message", "count"));
-
-			Tool dynamicTool = Tool.builder()
-				.name("dynamic-tool")
-				.description("Dynamically added tool")
-				.outputSchema(outputSchema)
-				.build();
-
-			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
-					(exchange, request) -> {
-						int count = (Integer) request.getOrDefault("count", 1);
-						return CallToolResult.builder()
-							.addTextContent("Dynamic tool executed " + count + " times")
-							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
-							.build();
-					});
-
-			// Add tool to server
-			mcpServer.addTool(toolSpec);
-
-			// Wait for tool list change notification
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(mcpClient.listTools().tools()).hasSize(1);
-			});
-
-			// Verify tool was added with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call dynamically added tool
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
-				.isEqualTo("Dynamic tool executed 3 times");
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"count":3,"message":"Dynamic execution"}"""));
+	@AfterEach
+	public void after() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
 		}
-
-		mcpServer.close();
-	}
-
-	private double evaluateExpression(String expression) {
-		// Simple expression evaluator for testing
-		return switch (expression) {
-			case "2 + 3" -> 5.0;
-			case "10 * 2" -> 20.0;
-			case "7 + 8" -> 15.0;
-			case "5 + 3" -> 8.0;
-			default -> 0.0;
-		};
 	}
 
 }
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
index 0327e6b53..302c58c5f 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
@@ -4,51 +4,29 @@
 
 package io.modelcontextprotocol;
 
+import java.time.Duration;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+
 import com.fasterxml.jackson.databind.ObjectMapper;
+
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
 import io.modelcontextprotocol.server.McpServer;
-import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.McpServer.StatelessAsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.StatelessSyncSpecification;
 import io.modelcontextprotocol.server.TestUtil;
 import io.modelcontextprotocol.server.transport.WebFluxStatelessServerTransport;
-import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
-import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
-import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
-import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
-import io.modelcontextprotocol.spec.McpSchema.Prompt;
-import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
-import io.modelcontextprotocol.spec.McpSchema.PromptReference;
-import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.Tool;
-import io.modelcontextprotocol.server.McpTransportContext;
-import net.javacrumbs.jsonunit.core.Option;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
-import org.springframework.http.server.reactive.HttpHandler;
-import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
-import org.springframework.web.client.RestClient;
-import org.springframework.web.reactive.function.client.WebClient;
-import org.springframework.web.reactive.function.server.RouterFunctions;
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
 
-import java.time.Duration;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.BiFunction;
-
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.awaitility.Awaitility.await;
-
-class WebFluxStatelessIntegrationTests {
+class WebFluxStatelessIntegrationTests extends AbstractStatelessIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
 
@@ -58,19 +36,8 @@ class WebFluxStatelessIntegrationTests {
 
 	private WebFluxStatelessServerTransport mcpStreamableServerTransport;
 
-	ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
-
-	@BeforeEach
-	public void before() {
-		this.mcpStreamableServerTransport = WebFluxStatelessServerTransport.builder()
-			.objectMapper(new ObjectMapper())
-			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
-			.build();
-
-		HttpHandler httpHandler = RouterFunctions.toHttpHandler(mcpStreamableServerTransport.getRouterFunction());
-		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
-		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
-
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
 		clientBuilders
 			.put("httpclient",
 					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
@@ -83,391 +50,37 @@ public void before() {
 					.build())
 				.initializationTimeout(Duration.ofHours(10))
 				.requestTimeout(Duration.ofHours(10)));
-
-	}
-
-	@AfterEach
-	public void after() {
-		if (httpServer != null) {
-			httpServer.disposeNow();
-		}
-	}
-
-	// ---------------------------------------
-	// Tools Tests
-	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-			"$schema": "http://json-schema.org/draft-07/schema#",
-			"type": "object",
-			"properties": {}
-			}
-			""";
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testToolCallSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpStatelessServerFeatures.SyncToolSpecification tool1 = new McpStatelessServerFeatures.SyncToolSpecification(
-				new Tool("tool1", "tool1 description", emptyJsonSchema), (transportContext, request) -> {
-					// perform a blocking call to a remote service
-					String response = RestClient.create()
-						.get()
-						.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-						.retrieve()
-						.body(String.class);
-					assertThat(response).isNotBlank();
-					return callResponse;
-				});
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testInitialize(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransport).build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Completion Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : Completion call")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var expectedValues = List.of("python", "pytorch", "pyside");
-		var completionResponse = new CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
-				true // hasMore
-		));
-
-		AtomicReference samplingRequest = new AtomicReference<>();
-		BiFunction completionHandler = (transportContext,
-				request) -> {
-			samplingRequest.set(request);
-			return completionResponse;
-		};
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
-			.capabilities(ServerCapabilities.builder().completions().build())
-			.prompts(new McpStatelessServerFeatures.SyncPromptSpecification(
-					new Prompt("code_review", "Code review", "this is code review prompt",
-							List.of(new PromptArgument("language", "Language", "string", false))),
-					(transportContext, getPromptRequest) -> null))
-			.completions(new McpStatelessServerFeatures.SyncCompletionSpecification(
-					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CompleteRequest request = new CompleteRequest(
-					new PromptReference("ref/prompt", "code_review", "Code review"),
-					new CompleteRequest.CompleteArgument("language", "py"));
-
-			CompleteResult result = mcpClient.completeCompletion(request);
-
-			assertThat(result).isNotNull();
-
-			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
-			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
-			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
-		}
-
-		mcpServer.close();
 	}
 
-	// ---------------------------------------
-	// Tool Structured Output Schema Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputValidationSuccess(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of(
-				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
-						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
-				"required", List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
-				calculatorTool, (transportContext, request) -> {
-					String expression = (String) request.arguments().getOrDefault("expression", "2 + 3");
-					double result = evaluateExpression(expression);
-					return CallToolResult.builder()
-						.structuredContent(
-								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Verify tool is listed with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call tool with valid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-		}
-
-		mcpServer.close();
+	@Override
+	protected StatelessAsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(this.mcpStreamableServerTransport);
 	}
 
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputValidationFailure(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
-				List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
-				calculatorTool, (transportContext, request) -> {
-					// Return invalid structured output. Result should be number, missing
-					// operation
-					return CallToolResult.builder()
-						.addTextContent("Invalid calculation")
-						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool with invalid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).contains("Validation failed");
-		}
-
-		mcpServer.close();
+	@Override
+	protected StatelessSyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(this.mcpStreamableServerTransport);
 	}
 
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputMissingStructuredContent(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpStatelessServerFeatures.SyncToolSpecification tool = new McpStatelessServerFeatures.SyncToolSpecification(
-				calculatorTool, (transportContext, request) -> {
-					// Return result without structured content but tool has output schema
-					return CallToolResult.builder().addTextContent("Calculation completed").build();
-				});
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.instructions("bla")
-			.tools(tool)
+	@BeforeEach
+	public void before() {
+		this.mcpStreamableServerTransport = WebFluxStatelessServerTransport.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.build();
 
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool that should return structured content but doesn't
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).isEqualTo(
-					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
-		}
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(mcpStreamableServerTransport.getRouterFunction());
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
 
-		mcpServer.close();
+		prepareClients(PORT, null);
 	}
 
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputRuntimeToolAddition(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Start server without tools
-		var mcpServer = McpServer.sync(mcpStreamableServerTransport)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Initially no tools
-			assertThat(mcpClient.listTools().tools()).isEmpty();
-
-			// Add tool with output schema at runtime
-			Map outputSchema = Map.of("type", "object", "properties",
-					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
-					List.of("message", "count"));
-
-			Tool dynamicTool = Tool.builder()
-				.name("dynamic-tool")
-				.description("Dynamically added tool")
-				.outputSchema(outputSchema)
-				.build();
-
-			McpStatelessServerFeatures.SyncToolSpecification toolSpec = new McpStatelessServerFeatures.SyncToolSpecification(
-					dynamicTool, (transportContext, request) -> {
-						int count = (Integer) request.arguments().getOrDefault("count", 1);
-						return CallToolResult.builder()
-							.addTextContent("Dynamic tool executed " + count + " times")
-							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
-							.build();
-					});
-
-			// Add tool to server
-			mcpServer.addTool(toolSpec);
-
-			// Wait for tool list change notification
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(mcpClient.listTools().tools()).hasSize(1);
-			});
-
-			// Verify tool was added with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call dynamically added tool
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
-				.isEqualTo("Dynamic tool executed 3 times");
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"count":3,"message":"Dynamic execution"}"""));
+	@AfterEach
+	public void after() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
 		}
-
-		mcpServer.close();
-	}
-
-	private double evaluateExpression(String expression) {
-		// Simple expression evaluator for testing
-		return switch (expression) {
-			case "2 + 3" -> 5.0;
-			case "10 * 2" -> 20.0;
-			case "7 + 8" -> 15.0;
-			case "5 + 3" -> 8.0;
-			default -> 0.0;
-		};
 	}
 
 }
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
index 5cd19e627..616c6dcf8 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -4,70 +4,29 @@
 
 package io.modelcontextprotocol;
 
+import java.time.Duration;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+
 import com.fasterxml.jackson.databind.ObjectMapper;
+
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
 import io.modelcontextprotocol.server.McpServer;
-import io.modelcontextprotocol.server.McpServerFeatures;
-import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.SyncSpecification;
 import io.modelcontextprotocol.server.TestUtil;
 import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
-import io.modelcontextprotocol.spec.McpError;
-import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
-import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
-import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
-import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
-import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
-import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
-import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
-import io.modelcontextprotocol.spec.McpSchema.Prompt;
-import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
-import io.modelcontextprotocol.spec.McpSchema.PromptReference;
-import io.modelcontextprotocol.spec.McpSchema.Role;
-import io.modelcontextprotocol.spec.McpSchema.Root;
-import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.Tool;
-import net.javacrumbs.jsonunit.core.Option;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
-import org.springframework.http.server.reactive.HttpHandler;
-import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
-import org.springframework.web.client.RestClient;
-import org.springframework.web.reactive.function.client.WebClient;
-import org.springframework.web.reactive.function.server.RouterFunctions;
-import reactor.core.publisher.Mono;
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
-import reactor.test.StepVerifier;
-
-import java.time.Duration;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.CopyOnWriteArrayList;
-import java.util.concurrent.CountDownLatch;
-import java.util.concurrent.TimeUnit;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.BiFunction;
-import java.util.function.Function;
-import java.util.stream.Collectors;
 
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.assertj.core.api.Assertions.assertWith;
-import static org.awaitility.Awaitility.await;
-import static org.mockito.Mockito.mock;
-
-class WebFluxStreamableIntegrationTests {
+class WebFluxStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
 
@@ -77,7 +36,32 @@ class WebFluxStreamableIntegrationTests {
 
 	private WebFluxStreamableServerTransportProvider mcpStreamableServerTransportProvider;
 
-	ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+						.endpoint(CUSTOM_MESSAGE_ENDPOINT)
+						.build()).requestTimeout(Duration.ofHours(10)));
+		clientBuilders.put("webflux",
+				McpClient
+					.sync(WebClientStreamableHttpTransport
+						.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
+						.endpoint(CUSTOM_MESSAGE_ENDPOINT)
+						.build())
+					.requestTimeout(Duration.ofHours(10)));
+	}
+
+	@Override
+	protected AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(mcpStreamableServerTransportProvider);
+	}
+
+	@Override
+	protected SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(mcpStreamableServerTransportProvider);
+	}
 
 	@BeforeEach
 	public void before() {
@@ -92,19 +76,7 @@ public void before() {
 		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
 		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
 
-		clientBuilders
-			.put("httpclient",
-					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
-						.endpoint(CUSTOM_MESSAGE_ENDPOINT)
-						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
-		clientBuilders
-			.put("webflux", McpClient
-				.sync(WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
-					.endpoint(CUSTOM_MESSAGE_ENDPOINT)
-					.build())
-				.initializationTimeout(Duration.ofHours(10))
-				.requestTimeout(Duration.ofHours(10)));
-
+		prepareClients(PORT, null);
 	}
 
 	@AfterEach
@@ -114,1380 +86,4 @@ public void after() {
 		}
 	}
 
-	// ---------------------------------------
-	// Sampling Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageWithoutSamplingCapabilities(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> exchange.createMessage(mock(CreateMessageRequest.class))
-				.thenReturn(mock(CallToolResult.class)))
-			.build();
-
-		var server = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
-			.build();) {
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with sampling capabilities");
-			}
-		}
-		server.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-
-		AtomicReference samplingResult = new AtomicReference<>();
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var createMessageRequest = CreateMessageRequest.builder()
-					.messages(List
-						.of(new McpSchema.SamplingMessage(Role.USER, new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				return exchange.createMessage(createMessageRequest)
-					.doOnNext(samplingResult::set)
-					.thenReturn(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-
-			assertWith(samplingResult.get(), result -> {
-				assertThat(result).isNotNull();
-				assertThat(result.role()).isEqualTo(Role.USER);
-				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-				assertThat(result.model()).isEqualTo("MockModelName");
-				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-			});
-		}
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws InterruptedException {
-
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		// Server
-
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-
-		AtomicReference samplingResult = new AtomicReference<>();
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = CreateMessageRequest.builder()
-					.messages(List
-						.of(new McpSchema.SamplingMessage(Role.USER, new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				return exchange.createMessage(craeteMessageRequest)
-					.doOnNext(samplingResult::set)
-					.thenReturn(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.requestTimeout(Duration.ofSeconds(4))
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-
-			assertWith(samplingResult.get(), result -> {
-				assertThat(result).isNotNull();
-				assertThat(result.role()).isEqualTo(Role.USER);
-				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-				assertThat(result.model()).isEqualTo("MockModelName");
-				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-			});
-		}
-
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateMessageWithRequestTimeoutFail(String clientType) throws InterruptedException {
-
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		// Server
-
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = CreateMessageRequest.builder()
-					.messages(List
-						.of(new McpSchema.SamplingMessage(Role.USER, new McpSchema.TextContent("Test message"))))
-					.build();
-
-				return exchange.createMessage(craeteMessageRequest).thenReturn(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.requestTimeout(Duration.ofSeconds(1))
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}).withMessageContaining("within 1000ms");
-
-		}
-
-		mcpServer.closeGracefully().block();
-	}
-
-	// ---------------------------------------
-	// Elicitation Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> exchange.createElicitation(mock(ElicitRequest.class))
-				.then(Mono.just(mock(CallToolResult.class))))
-			.build();
-
-		var server = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (
-				// Create client without elicitation capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with elicitation capabilities");
-			}
-		}
-		server.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
-
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(3))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCreateElicitationWithRequestTimeoutFail(String clientType) {
-
-		var latch = new CountDownLatch(1);
-		// Client
-		var clientBuilder = clientBuilders.get(clientType);
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-
-			try {
-				if (!latch.await(2, TimeUnit.SECONDS)) {
-					throw new RuntimeException("Timeout waiting for elicitation processing");
-				}
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-
-		AtomicReference resultRef = new AtomicReference<>();
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				return exchange.createElicitation(elicitationRequest)
-					.doOnNext(resultRef::set)
-					.then(Mono.just(callResponse));
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1)) // 1 second.
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("within 1000ms");
-
-		ElicitResult elicitResult = resultRef.get();
-		assertThat(elicitResult).isNull();
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	// ---------------------------------------
-	// Roots Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsSuccess(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		List roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-
-			// Remove a root
-			mcpClient.removeRoot(roots.get(0).uri());
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
-			});
-
-			// Add a new root
-			var root3 = new Root("uri3://", "root3");
-			mcpClient.addRoot(root3);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsWithoutCapability(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.listRoots(); // try to list roots
-
-				return mock(CallToolResult.class);
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> {
-			})
-			.tools(tool)
-			.build();
-
-		// Create client without roots capability
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().build()).build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			// Attempt to list roots should fail
-			try {
-				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
-			}
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsNotificationWithEmptyRootsList(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(List.of()) // Empty roots list
-			.build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsWithMultipleHandlers(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef1 = new AtomicReference<>();
-		AtomicReference> rootsRef2 = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef1.set(rootsUpdate))
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef2.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef1.get()).containsAll(roots);
-				assertThat(rootsRef2.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testRootsServerCloseWithActiveSubscription(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Tools Tests
-	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-			"$schema": "http://json-schema.org/draft-07/schema#",
-			"type": "object",
-			"properties": {}
-			}
-			""";
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testToolCallSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testToolListChangeHandlingSuccess(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
-			// perform a blocking call to a remote service
-			String response = RestClient.create()
-				.get()
-				.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-				.retrieve()
-				.body(String.class);
-			assertThat(response).isNotBlank();
-			rootsRef.set(toolsUpdate);
-		}).build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			mcpServer.notifyToolsListChanged();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
-			});
-
-			// Remove a tool
-			mcpServer.removeTool("tool1");
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-
-			// Add a new tool
-			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
-				.tool(new Tool("tool2", "tool2 description", emptyJsonSchema))
-				.callHandler((exchange, request) -> callResponse)
-				.build();
-
-			mcpServer.addTool(tool2);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testInitialize(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider).build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Logging Tests
-	// ---------------------------------------
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testLoggingNotification(String clientType) throws InterruptedException {
-		int expectedNotificationsCount = 3;
-		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
-		// Create a list to store received logging notifications
-		List receivedNotifications = new CopyOnWriteArrayList<>();
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create server with a tool that sends logging notifications
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("logging-test", "Test logging notifications", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				// Create and send notifications with different levels
-
-			//@formatter:off
-					return exchange // This should be filtered out (DEBUG < NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.DEBUG)
-								.logger("test-logger")
-								.data("Debug message")
-								.build())
-					.then(exchange // This should be sent (NOTICE >= NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.NOTICE)
-								.logger("test-logger")
-								.data("Notice message")
-								.build()))
-					.then(exchange // This should be sent (ERROR > NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-							.level(McpSchema.LoggingLevel.ERROR)
-							.logger("test-logger")
-							.data("Error message")
-							.build()))
-					.then(exchange // This should be filtered out (INFO < NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.INFO)
-								.logger("test-logger")
-								.data("Another info message")
-								.build()))
-					.then(exchange // This should be sent (ERROR >= NOTICE)
-						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-								.level(McpSchema.LoggingLevel.ERROR)
-								.logger("test-logger")
-								.data("Another error message")
-								.build()))
-					.thenReturn(new CallToolResult("Logging test completed", false));
-					//@formatter:on
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (
-				// Create client with logging notification handler
-				var mcpClient = clientBuilder.loggingConsumer(notification -> {
-					receivedNotifications.add(notification);
-					latch.countDown();
-				}).build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Set minimum logging level to NOTICE
-			mcpClient.setLoggingLevel(McpSchema.LoggingLevel.NOTICE);
-
-			// Call the tool that sends logging notifications
-			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Logging test completed");
-
-			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
-
-			// Should have received 3 notifications (1 NOTICE and 2 ERROR)
-			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
-
-			Map notificationMap = receivedNotifications.stream()
-				.collect(Collectors.toMap(n -> n.data(), n -> n));
-
-			// First notification should be NOTICE level
-			assertThat(notificationMap.get("Notice message").level()).isEqualTo(McpSchema.LoggingLevel.NOTICE);
-			assertThat(notificationMap.get("Notice message").logger()).isEqualTo("test-logger");
-			assertThat(notificationMap.get("Notice message").data()).isEqualTo("Notice message");
-
-			// Second notification should be ERROR level
-			assertThat(notificationMap.get("Error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
-			assertThat(notificationMap.get("Error message").logger()).isEqualTo("test-logger");
-			assertThat(notificationMap.get("Error message").data()).isEqualTo("Error message");
-
-			// Third notification should be ERROR level
-			assertThat(notificationMap.get("Another error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
-			assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
-			assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
-		}
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Progress Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testProgressNotification(String clientType) throws InterruptedException {
-		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
-											// token
-		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
-		// Create a list to store received logging notifications
-		List receivedNotifications = new CopyOnWriteArrayList<>();
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create server with a tool that sends logging notifications
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder()
-				.name("progress-test")
-				.description("Test progress notifications")
-				.inputSchema(emptyJsonSchema)
-				.build())
-			.callHandler((exchange, request) -> {
-
-				// Create and send notifications
-				var progressToken = (String) request.meta().get("progressToken");
-
-				return exchange
-					.progressNotification(
-							new McpSchema.ProgressNotification(progressToken, 0.0, 1.0, "Processing started"))
-					.then(exchange.progressNotification(
-							new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Processing data")))
-					.then(// Send a progress notification with another progress value
-							// should
-							exchange.progressNotification(new McpSchema.ProgressNotification("another-progress-token",
-									0.0, 1.0, "Another processing started")))
-					.then(exchange.progressNotification(
-							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
-					.thenReturn(new CallToolResult(("Progress test completed"), false));
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (
-				// Create client with progress notification handler
-				var mcpClient = clientBuilder.progressConsumer(notification -> {
-					receivedNotifications.add(notification);
-					latch.countDown();
-				}).build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call the tool that sends progress notifications
-			McpSchema.CallToolRequest callToolRequest = McpSchema.CallToolRequest.builder()
-				.name("progress-test")
-				.meta(Map.of("progressToken", "test-progress-token"))
-				.build();
-			CallToolResult result = mcpClient.callTool(callToolRequest);
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
-
-			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
-
-			// Should have received 3 notifications
-			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
-
-			Map notificationMap = receivedNotifications.stream()
-				.collect(Collectors.toMap(n -> n.message(), n -> n));
-
-			// First notification should be 0.0/1.0 progress
-			assertThat(notificationMap.get("Processing started").progressToken()).isEqualTo("test-progress-token");
-			assertThat(notificationMap.get("Processing started").progress()).isEqualTo(0.0);
-			assertThat(notificationMap.get("Processing started").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing started").message()).isEqualTo("Processing started");
-
-			// Second notification should be 0.5/1.0 progress
-			assertThat(notificationMap.get("Processing data").progressToken()).isEqualTo("test-progress-token");
-			assertThat(notificationMap.get("Processing data").progress()).isEqualTo(0.5);
-			assertThat(notificationMap.get("Processing data").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing data").message()).isEqualTo("Processing data");
-
-			// Third notification should be another progress token with 0.0/1.0 progress
-			assertThat(notificationMap.get("Another processing started").progressToken())
-				.isEqualTo("another-progress-token");
-			assertThat(notificationMap.get("Another processing started").progress()).isEqualTo(0.0);
-			assertThat(notificationMap.get("Another processing started").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Another processing started").message())
-				.isEqualTo("Another processing started");
-
-			// Fourth notification should be 1.0/1.0 progress
-			assertThat(notificationMap.get("Processing completed").progressToken()).isEqualTo("test-progress-token");
-			assertThat(notificationMap.get("Processing completed").progress()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing completed").total()).isEqualTo(1.0);
-			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
-		}
-		finally {
-			mcpServer.close();
-		}
-	}
-
-	// ---------------------------------------
-	// Completion Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : Completion call")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var expectedValues = List.of("python", "pytorch", "pyside");
-		var completionResponse = new CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
-				true // hasMore
-		));
-
-		AtomicReference samplingRequest = new AtomicReference<>();
-		BiFunction completionHandler = (mcpSyncServerExchange,
-				request) -> {
-			samplingRequest.set(request);
-			return completionResponse;
-		};
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().completions().build())
-			.prompts(new McpServerFeatures.SyncPromptSpecification(
-					new Prompt("code_review", "Code review", "this is code review prompt",
-							List.of(new PromptArgument("language", "Language", "string", false))),
-					(mcpSyncServerExchange, getPromptRequest) -> null))
-			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CompleteRequest request = new CompleteRequest(
-					new PromptReference("ref/prompt", "code_review", "Code review"),
-					new CompleteRequest.CompleteArgument("language", "py"));
-
-			CompleteResult result = mcpClient.completeCompletion(request);
-
-			assertThat(result).isNotNull();
-
-			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
-			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
-			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Ping Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testPingSuccess(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create server with a tool that uses ping functionality
-		AtomicReference executionOrder = new AtomicReference<>("");
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new Tool("ping-async-test", "Test ping async behavior", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				executionOrder.set(executionOrder.get() + "1");
-
-				// Test async ping behavior
-				return exchange.ping().doOnNext(result -> {
-
-					assertThat(result).isNotNull();
-					// Ping should return an empty object or map
-					assertThat(result).isInstanceOf(Map.class);
-
-					executionOrder.set(executionOrder.get() + "2");
-					assertThat(result).isNotNull();
-				}).then(Mono.fromCallable(() -> {
-					executionOrder.set(executionOrder.get() + "3");
-					return new CallToolResult("Async ping test completed", false);
-				}));
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call the tool that tests ping async behavior
-			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("ping-async-test", Map.of()));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Async ping test completed");
-
-			// Verify execution order
-			assertThat(executionOrder.get()).isEqualTo("123");
-		}
-
-		mcpServer.closeGracefully().block();
-	}
-
-	// ---------------------------------------
-	// Tool Structured Output Schema Tests
-	// ---------------------------------------
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputValidationSuccess(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of(
-				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
-						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
-				"required", List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					String expression = (String) request.getOrDefault("expression", "2 + 3");
-					double result = evaluateExpression(expression);
-					return CallToolResult.builder()
-						.structuredContent(
-								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Verify tool is listed with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call tool with valid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputValidationFailure(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
-				List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return invalid structured output. Result should be number, missing
-					// operation
-					return CallToolResult.builder()
-						.addTextContent("Invalid calculation")
-						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool with invalid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).contains("Validation failed");
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputMissingStructuredContent(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return result without structured content but tool has output schema
-					return CallToolResult.builder().addTextContent("Calculation completed").build();
-				});
-
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.instructions("bla")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool that should return structured content but doesn't
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).isEqualTo(
-					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
-		}
-
-		mcpServer.close();
-	}
-
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void testStructuredOutputRuntimeToolAddition(String clientType) {
-		var clientBuilder = clientBuilders.get(clientType);
-
-		// Start server without tools
-		var mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Initially no tools
-			assertThat(mcpClient.listTools().tools()).isEmpty();
-
-			// Add tool with output schema at runtime
-			Map outputSchema = Map.of("type", "object", "properties",
-					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
-					List.of("message", "count"));
-
-			Tool dynamicTool = Tool.builder()
-				.name("dynamic-tool")
-				.description("Dynamically added tool")
-				.outputSchema(outputSchema)
-				.build();
-
-			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
-					(exchange, request) -> {
-						int count = (Integer) request.getOrDefault("count", 1);
-						return CallToolResult.builder()
-							.addTextContent("Dynamic tool executed " + count + " times")
-							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
-							.build();
-					});
-
-			// Add tool to server
-			mcpServer.addTool(toolSpec);
-
-			// Wait for tool list change notification
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(mcpClient.listTools().tools()).hasSize(1);
-			});
-
-			// Verify tool was added with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call dynamically added tool
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) response.content().get(0)).text())
-				.isEqualTo("Dynamic tool executed 3 times");
-
-			assertThat(response.structuredContent()).isNotNull();
-			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"count":3,"message":"Dynamic execution"}"""));
-		}
-
-		mcpServer.close();
-	}
-
-	private double evaluateExpression(String expression) {
-		// Simple expression evaluator for testing
-		return switch (expression) {
-			case "2 + 3" -> 5.0;
-			case "10 * 2" -> 20.0;
-			case "7 + 8" -> 15.0;
-			case "5 + 3" -> 8.0;
-			default -> 0.0;
-		};
-	}
-
 }
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index 45f6b94f0..995cbd165 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -42,11 +42,11 @@ protected void prepareClients(int port, String mcpEndpoint) {
 
 		clientBuilders.put("httpclient",
 				McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + port).build())
-					.initializationTimeout(Duration.ofHours(10))
 					.requestTimeout(Duration.ofHours(10)));
 
 		clientBuilders.put("webflux", McpClient
-			.sync(WebFluxSseClientTransport.builder(WebClient.builder().baseUrl("http://localhost:" + port)).build()));
+			.sync(WebFluxSseClientTransport.builder(WebClient.builder().baseUrl("http://localhost:" + port)).build())
+			.requestTimeout(Duration.ofHours(10)));
 	}
 
 	@Configuration
@@ -55,7 +55,10 @@ static class TestConfig {
 
 		@Bean
 		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
-			return new WebMvcSseServerTransportProvider(new ObjectMapper(), MESSAGE_ENDPOINT);
+			return WebMvcSseServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.messageEndpoint(MESSAGE_ENDPOINT)
+				.build();
 		}
 
 		@Bean
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
index b2264ea00..802363d59 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
@@ -11,8 +11,6 @@
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -29,7 +27,6 @@
 import io.modelcontextprotocol.server.McpServer.StatelessAsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.StatelessSyncSpecification;
 import io.modelcontextprotocol.server.transport.WebMvcStatelessServerTransport;
-import io.modelcontextprotocol.spec.McpSchema;
 import reactor.core.scheduler.Schedulers;
 
 class WebMvcStatelessIntegrationTests extends AbstractStatelessIntegrationTests {
@@ -63,6 +60,32 @@ public RouterFunction routerFunction(WebMvcStatelessServerTransp
 
 	private TomcatTestUtil.TomcatServer tomcatServer;
 
+	@Override
+	protected StatelessAsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(this.mcpServerTransport);
+	}
+
+	@Override
+	protected StatelessSyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(this.mcpServerTransport);
+	}
+
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
+
+		clientBuilders.put("httpclient", McpClient
+			.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + port).endpoint(mcpEndpoint).build())
+			.requestTimeout(Duration.ofHours(10)));
+
+		clientBuilders.put("webflux",
+				McpClient
+					.sync(WebClientStreamableHttpTransport
+						.builder(WebClient.builder().baseUrl("http://localhost:" + port))
+						.endpoint(mcpEndpoint)
+						.build())
+					.requestTimeout(Duration.ofHours(10)));
+	}
+
 	@BeforeEach
 	public void before() {
 
@@ -76,33 +99,13 @@ public void before() {
 			throw new RuntimeException("Failed to start Tomcat", e);
 		}
 
-		clientBuilders
-			.put("httpclient",
-					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
-						.endpoint(MESSAGE_ENDPOINT)
-						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
-
-		clientBuilders.put("webflux",
-				McpClient.sync(WebClientStreamableHttpTransport
-					.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
-					.endpoint(MESSAGE_ENDPOINT)
-					.build()));
+		prepareClients(PORT, MESSAGE_ENDPOINT);
 
 		// Get the transport from Spring context
 		this.mcpServerTransport = tomcatServer.appContext().getBean(WebMvcStatelessServerTransport.class);
 
 	}
 
-	@Override
-	protected StatelessAsyncSpecification prepareAsyncServerBuilder() {
-		return McpServer.async(this.mcpServerTransport);
-	}
-
-	@Override
-	protected StatelessSyncSpecification prepareSyncServerBuilder() {
-		return McpServer.sync(this.mcpServerTransport);
-	}
-
 	@AfterEach
 	public void after() {
 		reactor.netty.http.HttpResources.disposeLoopsAndConnections();
@@ -124,42 +127,4 @@ public void after() {
 		}
 	}
 
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void simple(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var server = McpServer.async(this.mcpServerTransport)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1000))
-			.build();
-
-		try (
-				// Create client without sampling capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
-					.requestTimeout(Duration.ofSeconds(1000))
-					.build()) {
-
-			assertThat(client.initialize()).isNotNull();
-
-		}
-		server.closeGracefully();
-	}
-
-	@Override
-	protected void prepareClients(int port, String mcpEndpoint) {
-
-		clientBuilders.put("httpclient", McpClient
-			.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + port).endpoint(mcpEndpoint).build())
-			.initializationTimeout(Duration.ofHours(10))
-			.requestTimeout(Duration.ofHours(10)));
-
-		clientBuilders.put("webflux",
-				McpClient.sync(WebClientStreamableHttpTransport
-					.builder(WebClient.builder().baseUrl("http://localhost:" + port))
-					.endpoint(mcpEndpoint)
-					.build()));
-	}
-
 }
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
index f99b016ff..84862f27e 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -124,42 +124,20 @@ public void after() {
 		}
 	}
 
-	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
-	void simple(String clientType) {
-
-		var clientBuilder = clientBuilders.get(clientType);
-
-		var server = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1000))
-			.build();
-
-		try (
-				// Create client without sampling capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
-					.requestTimeout(Duration.ofSeconds(1000))
-					.build()) {
-
-			assertThat(client.initialize()).isNotNull();
-
-		}
-		server.closeGracefully();
-	}
-
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 
 		clientBuilders.put("httpclient", McpClient
 			.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + port).endpoint(mcpEndpoint).build())
-			.initializationTimeout(Duration.ofHours(10))
 			.requestTimeout(Duration.ofHours(10)));
 
 		clientBuilders.put("webflux",
-				McpClient.sync(WebClientStreamableHttpTransport
-					.builder(WebClient.builder().baseUrl("http://localhost:" + port))
-					.endpoint(mcpEndpoint)
-					.build()));
+				McpClient
+					.sync(WebClientStreamableHttpTransport
+						.builder(WebClient.builder().baseUrl("http://localhost:" + port))
+						.endpoint(mcpEndpoint)
+						.build())
+					.requestTimeout(Duration.ofHours(10)));
 	}
 
 }
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index b3a699b94..ef6730a7c 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -19,10 +19,13 @@
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
 import java.util.function.Function;
+import java.util.stream.Collectors;
 
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
@@ -31,16 +34,22 @@
 import io.modelcontextprotocol.server.McpServer;
 import io.modelcontextprotocol.server.McpServerFeatures;
 import io.modelcontextprotocol.server.McpSyncServer;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
 import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
 import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
 import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
 import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
 import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
 import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
+import io.modelcontextprotocol.spec.McpSchema.Prompt;
+import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import io.modelcontextprotocol.spec.McpSchema.Role;
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
@@ -740,7 +749,6 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-
 	String emptyJsonSchema = """
 			{
 				"$schema": "http://json-schema.org/draft-07/schema#",
@@ -944,6 +952,276 @@ void testInitialize(String clientType) {
 		mcpServer.close();
 	}
 
+	// ---------------------------------------
+	// Logging Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testLoggingNotification(String clientType) throws InterruptedException {
+		int expectedNotificationsCount = 3;
+		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
+		// Create a list to store received logging notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		var clientBuilder = clientBuilders.get(clientType);
+		;
+		// Create server with a tool that sends logging notifications
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder()
+				.name("logging-test")
+				.description("Test logging notifications")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications with different levels
+
+			//@formatter:off
+					return exchange // This should be filtered out (DEBUG < NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.DEBUG)
+								.logger("test-logger")
+								.data("Debug message")
+								.build())
+					.then(exchange // This should be sent (NOTICE >= NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.NOTICE)
+								.logger("test-logger")
+								.data("Notice message")
+								.build()))
+					.then(exchange // This should be sent (ERROR > NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+							.level(McpSchema.LoggingLevel.ERROR)
+							.logger("test-logger")
+							.data("Error message")
+							.build()))
+					.then(exchange // This should be filtered out (INFO < NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.INFO)
+								.logger("test-logger")
+								.data("Another info message")
+								.build()))
+					.then(exchange // This should be sent (ERROR >= NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.ERROR)
+								.logger("test-logger")
+								.data("Another error message")
+								.build()))
+					.thenReturn(new CallToolResult("Logging test completed", false));
+					//@formatter:on
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client with logging notification handler
+				var mcpClient = clientBuilder.loggingConsumer(notification -> {
+					receivedNotifications.add(notification);
+					latch.countDown();
+				}).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Set minimum logging level to NOTICE
+			mcpClient.setLoggingLevel(McpSchema.LoggingLevel.NOTICE);
+
+			// Call the tool that sends logging notifications
+			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Logging test completed");
+
+			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
+
+			// Should have received 3 notifications (1 NOTICE and 2 ERROR)
+			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
+
+			Map notificationMap = receivedNotifications.stream()
+				.collect(Collectors.toMap(n -> n.data(), n -> n));
+
+			// First notification should be NOTICE level
+			assertThat(notificationMap.get("Notice message").level()).isEqualTo(McpSchema.LoggingLevel.NOTICE);
+			assertThat(notificationMap.get("Notice message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Notice message").data()).isEqualTo("Notice message");
+
+			// Second notification should be ERROR level
+			assertThat(notificationMap.get("Error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
+			assertThat(notificationMap.get("Error message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Error message").data()).isEqualTo("Error message");
+
+			// Third notification should be ERROR level
+			assertThat(notificationMap.get("Another error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
+			assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
+		}
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Progress Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testProgressNotification(String clientType) throws InterruptedException {
+		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
+											// token
+		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
+		// Create a list to store received logging notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that sends logging notifications
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(McpSchema.Tool.builder()
+				.name("progress-test")
+				.description("Test progress notifications")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications
+				var progressToken = (String) request.meta().get("progressToken");
+
+				return exchange
+					.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.0, 1.0, "Processing started"))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Processing data")))
+					.then(// Send a progress notification with another progress value
+							// should
+							exchange.progressNotification(new McpSchema.ProgressNotification("another-progress-token",
+									0.0, 1.0, "Another processing started")))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
+					.thenReturn(new CallToolResult(("Progress test completed"), false));
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client with progress notification handler
+				var mcpClient = clientBuilder.progressConsumer(notification -> {
+					receivedNotifications.add(notification);
+					latch.countDown();
+				}).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that sends progress notifications
+			McpSchema.CallToolRequest callToolRequest = McpSchema.CallToolRequest.builder()
+				.name("progress-test")
+				.meta(Map.of("progressToken", "test-progress-token"))
+				.build();
+			CallToolResult result = mcpClient.callTool(callToolRequest);
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
+
+			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
+
+			// Should have received 3 notifications
+			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
+
+			Map notificationMap = receivedNotifications.stream()
+				.collect(Collectors.toMap(n -> n.message(), n -> n));
+
+			// First notification should be 0.0/1.0 progress
+			assertThat(notificationMap.get("Processing started").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing started").message()).isEqualTo("Processing started");
+
+			// Second notification should be 0.5/1.0 progress
+			assertThat(notificationMap.get("Processing data").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing data").progress()).isEqualTo(0.5);
+			assertThat(notificationMap.get("Processing data").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing data").message()).isEqualTo("Processing data");
+
+			// Third notification should be another progress token with 0.0/1.0 progress
+			assertThat(notificationMap.get("Another processing started").progressToken())
+				.isEqualTo("another-progress-token");
+			assertThat(notificationMap.get("Another processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Another processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Another processing started").message())
+				.isEqualTo("Another processing started");
+
+			// Fourth notification should be 1.0/1.0 progress
+			assertThat(notificationMap.get("Processing completed").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing completed").progress()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
+		}
+		finally {
+			mcpServer.close();
+		}
+	}
+
+	// ---------------------------------------
+	// Completion Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : Completion call")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var expectedValues = List.of("python", "pytorch", "pyside");
+		var completionResponse = new McpSchema.CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
+				true // hasMore
+		));
+
+		AtomicReference samplingRequest = new AtomicReference<>();
+		BiFunction completionHandler = (mcpSyncServerExchange,
+				request) -> {
+			samplingRequest.set(request);
+			return completionResponse;
+		};
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().completions().build())
+			.prompts(new McpServerFeatures.SyncPromptSpecification(
+					new Prompt("code_review", "Code review", "this is code review prompt",
+							List.of(new PromptArgument("language", "Language", "string", false))),
+					(mcpSyncServerExchange, getPromptRequest) -> null))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(
+					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CompleteRequest request = new CompleteRequest(
+					new PromptReference("ref/prompt", "code_review", "Code review"),
+					new CompleteRequest.CompleteArgument("language", "py"));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			assertThat(result).isNotNull();
+
+			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
+			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Ping Tests
+	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testPingSuccess(String clientType) {
@@ -1006,7 +1284,6 @@ void testPingSuccess(String clientType) {
 	// ---------------------------------------
 	// Tool Structured Output Schema Tests
 	// ---------------------------------------
-
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testStructuredOutputValidationSuccess(String clientType) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index a53501898..28b353d32 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -19,10 +19,13 @@
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
 import java.util.function.Function;
+import java.util.stream.Collectors;
 
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
@@ -32,6 +35,8 @@
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
 import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
 import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
 import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
@@ -737,7 +742,6 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-
 	String emptyJsonSchema = """
 			{
 				"$schema": "http://json-schema.org/draft-07/schema#",
@@ -941,6 +945,276 @@ void testInitialize(String clientType) {
 		mcpServer.close();
 	}
 
+	// ---------------------------------------
+	// Logging Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testLoggingNotification(String clientType) throws InterruptedException {
+		int expectedNotificationsCount = 3;
+		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
+		// Create a list to store received logging notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		var clientBuilder = clientBuilders.get(clientType);
+		;
+		// Create server with a tool that sends logging notifications
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(Tool.builder()
+				.name("logging-test")
+				.description("Test logging notifications")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications with different levels
+
+			//@formatter:off
+					return exchange // This should be filtered out (DEBUG < NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.DEBUG)
+								.logger("test-logger")
+								.data("Debug message")
+								.build())
+					.then(exchange // This should be sent (NOTICE >= NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.NOTICE)
+								.logger("test-logger")
+								.data("Notice message")
+								.build()))
+					.then(exchange // This should be sent (ERROR > NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+							.level(McpSchema.LoggingLevel.ERROR)
+							.logger("test-logger")
+							.data("Error message")
+							.build()))
+					.then(exchange // This should be filtered out (INFO < NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.INFO)
+								.logger("test-logger")
+								.data("Another info message")
+								.build()))
+					.then(exchange // This should be sent (ERROR >= NOTICE)
+						.loggingNotification(McpSchema.LoggingMessageNotification.builder()
+								.level(McpSchema.LoggingLevel.ERROR)
+								.logger("test-logger")
+								.data("Another error message")
+								.build()))
+					.thenReturn(new CallToolResult("Logging test completed", false));
+					//@formatter:on
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client with logging notification handler
+				var mcpClient = clientBuilder.loggingConsumer(notification -> {
+					receivedNotifications.add(notification);
+					latch.countDown();
+				}).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Set minimum logging level to NOTICE
+			mcpClient.setLoggingLevel(McpSchema.LoggingLevel.NOTICE);
+
+			// Call the tool that sends logging notifications
+			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Logging test completed");
+
+			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
+
+			// Should have received 3 notifications (1 NOTICE and 2 ERROR)
+			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
+
+			Map notificationMap = receivedNotifications.stream()
+				.collect(Collectors.toMap(n -> n.data(), n -> n));
+
+			// First notification should be NOTICE level
+			assertThat(notificationMap.get("Notice message").level()).isEqualTo(McpSchema.LoggingLevel.NOTICE);
+			assertThat(notificationMap.get("Notice message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Notice message").data()).isEqualTo("Notice message");
+
+			// Second notification should be ERROR level
+			assertThat(notificationMap.get("Error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
+			assertThat(notificationMap.get("Error message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Error message").data()).isEqualTo("Error message");
+
+			// Third notification should be ERROR level
+			assertThat(notificationMap.get("Another error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
+			assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
+			assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
+		}
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Progress Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testProgressNotification(String clientType) throws InterruptedException {
+		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
+											// token
+		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
+		// Create a list to store received logging notifications
+		List receivedNotifications = new CopyOnWriteArrayList<>();
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create server with a tool that sends logging notifications
+		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
+			.tool(McpSchema.Tool.builder()
+				.name("progress-test")
+				.description("Test progress notifications")
+				.inputSchema(emptyJsonSchema)
+				.build())
+			.callHandler((exchange, request) -> {
+
+				// Create and send notifications
+				var progressToken = (String) request.meta().get("progressToken");
+
+				return exchange
+					.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.0, 1.0, "Processing started"))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Processing data")))
+					.then(// Send a progress notification with another progress value
+							// should
+							exchange.progressNotification(new McpSchema.ProgressNotification("another-progress-token",
+									0.0, 1.0, "Another processing started")))
+					.then(exchange.progressNotification(
+							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
+					.thenReturn(new CallToolResult(("Progress test completed"), false));
+			})
+			.build();
+
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (
+				// Create client with progress notification handler
+				var mcpClient = clientBuilder.progressConsumer(notification -> {
+					receivedNotifications.add(notification);
+					latch.countDown();
+				}).build()) {
+
+			// Initialize client
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Call the tool that sends progress notifications
+			McpSchema.CallToolRequest callToolRequest = McpSchema.CallToolRequest.builder()
+				.name("progress-test")
+				.meta(Map.of("progressToken", "test-progress-token"))
+				.build();
+			CallToolResult result = mcpClient.callTool(callToolRequest);
+			assertThat(result).isNotNull();
+			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
+
+			assertThat(latch.await(5, TimeUnit.SECONDS)).as("Should receive notifications in reasonable time").isTrue();
+
+			// Should have received 3 notifications
+			assertThat(receivedNotifications).hasSize(expectedNotificationsCount);
+
+			Map notificationMap = receivedNotifications.stream()
+				.collect(Collectors.toMap(n -> n.message(), n -> n));
+
+			// First notification should be 0.0/1.0 progress
+			assertThat(notificationMap.get("Processing started").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing started").message()).isEqualTo("Processing started");
+
+			// Second notification should be 0.5/1.0 progress
+			assertThat(notificationMap.get("Processing data").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing data").progress()).isEqualTo(0.5);
+			assertThat(notificationMap.get("Processing data").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing data").message()).isEqualTo("Processing data");
+
+			// Third notification should be another progress token with 0.0/1.0 progress
+			assertThat(notificationMap.get("Another processing started").progressToken())
+				.isEqualTo("another-progress-token");
+			assertThat(notificationMap.get("Another processing started").progress()).isEqualTo(0.0);
+			assertThat(notificationMap.get("Another processing started").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Another processing started").message())
+				.isEqualTo("Another processing started");
+
+			// Fourth notification should be 1.0/1.0 progress
+			assertThat(notificationMap.get("Processing completed").progressToken()).isEqualTo("test-progress-token");
+			assertThat(notificationMap.get("Processing completed").progress()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").total()).isEqualTo(1.0);
+			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
+		}
+		finally {
+			mcpServer.close();
+		}
+	}
+
+	// ---------------------------------------
+	// Completion Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : Completion call")
+	@ValueSource(strings = { "httpclient" })
+	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var expectedValues = List.of("python", "pytorch", "pyside");
+		var completionResponse = new McpSchema.CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
+				true // hasMore
+		));
+
+		AtomicReference samplingRequest = new AtomicReference<>();
+		BiFunction completionHandler = (mcpSyncServerExchange,
+				request) -> {
+			samplingRequest.set(request);
+			return completionResponse;
+		};
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().completions().build())
+			.prompts(new McpServerFeatures.SyncPromptSpecification(
+					new McpSchema.Prompt("code_review", "Code review", "this is code review prompt",
+							List.of(new McpSchema.PromptArgument("language", "Language", "string", false))),
+					(mcpSyncServerExchange, getPromptRequest) -> null))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(
+					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CompleteRequest request = new CompleteRequest(
+					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"),
+					new CompleteRequest.CompleteArgument("language", "py"));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			assertThat(result).isNotNull();
+
+			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
+			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+		}
+
+		mcpServer.close();
+	}
+
+	// ---------------------------------------
+	// Ping Tests
+	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testPingSuccess(String clientType) {
@@ -1003,7 +1277,6 @@ void testPingSuccess(String clientType) {
 	// ---------------------------------------
 	// Tool Structured Output Schema Tests
 	// ---------------------------------------
-
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testStructuredOutputValidationSuccess(String clientType) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
new file mode 100644
index 000000000..56e74218f
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
@@ -0,0 +1,93 @@
+/*
+ * Copyright 2024 - 2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.Duration;
+
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
+import io.modelcontextprotocol.server.McpServer.SyncSpecification;
+import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+
+class HttpServletSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
+
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
+	private static final String CUSTOM_SSE_ENDPOINT = "/somePath/sse";
+
+	private static final String CUSTOM_MESSAGE_ENDPOINT = "/otherPath/mcp/message";
+
+	private HttpServletSseServerTransportProvider mcpServerTransportProvider;
+
+	private Tomcat tomcat;
+
+	@BeforeEach
+	public void before() {
+		// Create and configure the transport provider
+		mcpServerTransportProvider = HttpServletSseServerTransportProvider.builder()
+			.objectMapper(new ObjectMapper())
+			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
+			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
+			.build();
+
+		tomcat = TomcatTestUtil.createTomcatServer("", PORT, mcpServerTransportProvider);
+		try {
+			tomcat.start();
+			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		clientBuilders
+			.put("httpclient",
+					McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT)
+						.sseEndpoint(CUSTOM_SSE_ENDPOINT)
+						.build()).requestTimeout(Duration.ofHours(10)));
+	}
+
+	@Override
+	protected AsyncSpecification prepareAsyncServerBuilder() {
+		return McpServer.async(this.mcpServerTransportProvider);
+	}
+
+	@Override
+	protected SyncSpecification prepareSyncServerBuilder() {
+		return McpServer.sync(this.mcpServerTransportProvider);
+	}
+
+	@AfterEach
+	public void after() {
+		if (mcpServerTransportProvider != null) {
+			mcpServerTransportProvider.closeGracefully().block();
+		}
+		if (tomcat != null) {
+			try {
+				tomcat.stop();
+				tomcat.destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	@Override
+	protected void prepareClients(int port, String mcpEndpoint) {
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 07c6e7c5c..6ac10014e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -55,7 +55,7 @@ public void before() {
 			.put("httpclient",
 					McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
 						.endpoint(MESSAGE_ENDPOINT)
-						.build()).initializationTimeout(Duration.ofHours(10)).requestTimeout(Duration.ofHours(10)));
+						.build()).requestTimeout(Duration.ofHours(10)));
 	}
 
 	@Override
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
deleted file mode 100644
index bf38e68ec..000000000
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProviderIntegrationTests.java
+++ /dev/null
@@ -1,1390 +0,0 @@
-/*
- * Copyright 2024 - 2025 the original author or authors.
- */
-
-package io.modelcontextprotocol.server.transport;
-
-import java.time.Duration;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.CopyOnWriteArrayList;
-import java.util.concurrent.TimeUnit;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.Function;
-import java.util.stream.Collectors;
-
-import com.fasterxml.jackson.databind.ObjectMapper;
-
-import io.modelcontextprotocol.client.McpClient;
-import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
-import io.modelcontextprotocol.server.McpServer;
-import io.modelcontextprotocol.server.McpServerFeatures;
-import io.modelcontextprotocol.spec.McpError;
-import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
-import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
-import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
-import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
-import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
-import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
-import io.modelcontextprotocol.spec.McpSchema.Role;
-import io.modelcontextprotocol.spec.McpSchema.Root;
-import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.Tool;
-import net.javacrumbs.jsonunit.core.Option;
-
-import org.apache.catalina.LifecycleException;
-import org.apache.catalina.LifecycleState;
-import org.apache.catalina.startup.Tomcat;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import reactor.core.publisher.Mono;
-import reactor.test.StepVerifier;
-
-import org.springframework.web.client.RestClient;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.assertj.core.api.InstanceOfAssertFactories.type;
-import static org.awaitility.Awaitility.await;
-import static org.mockito.Mockito.mock;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-
-class HttpServletSseServerTransportProviderIntegrationTests {
-
-	private static final int PORT = TomcatTestUtil.findAvailablePort();
-
-	private static final String CUSTOM_SSE_ENDPOINT = "/somePath/sse";
-
-	private static final String CUSTOM_MESSAGE_ENDPOINT = "/otherPath/mcp/message";
-
-	private HttpServletSseServerTransportProvider mcpServerTransportProvider;
-
-	McpClient.SyncSpec clientBuilder;
-
-	private Tomcat tomcat;
-
-	@BeforeEach
-	public void before() {
-		// Create and configure the transport provider
-		mcpServerTransportProvider = HttpServletSseServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
-			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
-			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
-			.build();
-
-		tomcat = TomcatTestUtil.createTomcatServer("", PORT, mcpServerTransportProvider);
-		try {
-			tomcat.start();
-			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
-		}
-		catch (Exception e) {
-			throw new RuntimeException("Failed to start Tomcat", e);
-		}
-
-		this.clientBuilder = McpClient.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT)
-			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
-			.build());
-	}
-
-	@AfterEach
-	public void after() {
-		if (mcpServerTransportProvider != null) {
-			mcpServerTransportProvider.closeGracefully().block();
-		}
-		if (tomcat != null) {
-			try {
-				tomcat.stop();
-				tomcat.destroy();
-			}
-			catch (LifecycleException e) {
-				throw new RuntimeException("Failed to stop Tomcat", e);
-			}
-		}
-	}
-
-	// ---------------------------------------
-	// Sampling Tests
-	// ---------------------------------------
-	@Test
-	// @Disabled
-	void testCreateMessageWithoutSamplingCapabilities() {
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
-
-				return Mono.just(mock(CallToolResult.class));
-			})
-			.build();
-
-		var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build();
-
-		try (
-				// Create client without sampling capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
-					.build()) {
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with sampling capabilities");
-			}
-		}
-		server.close();
-	}
-
-	@Test
-	void testCreateMessageSuccess() {
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-		mcpServer.close();
-	}
-
-	@Test
-	void testCreateMessageWithRequestTimeoutSuccess() throws InterruptedException {
-
-		// Client
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(3))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-
-		mcpClient.close();
-		mcpServer.close();
-	}
-
-	@Test
-	void testCreateMessageWithRequestTimeoutFail() throws InterruptedException {
-
-		// Client
-
-		Function samplingHandler = request -> {
-			assertThat(request.messages()).hasSize(1);
-			assertThat(request.messages().get(0).content()).isInstanceOf(McpSchema.TextContent.class);
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new CreateMessageResult(Role.USER, new McpSchema.TextContent("Test message"), "MockModelName",
-					CreateMessageResult.StopReason.STOP_SEQUENCE);
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var craeteMessageRequest = McpSchema.CreateMessageRequest.builder()
-					.messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
-							new McpSchema.TextContent("Test message"))))
-					.modelPreferences(ModelPreferences.builder()
-						.hints(List.of())
-						.costPriority(1.0)
-						.speedPriority(1.0)
-						.intelligencePriority(1.0)
-						.build())
-					.build();
-
-				StepVerifier.create(exchange.createMessage(craeteMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("Timeout");
-
-		mcpClient.close();
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Elicitation Tests
-	// ---------------------------------------
-	@Test
-	// @Disabled
-	void testCreateElicitationWithoutElicitationCapabilities() {
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.createElicitation(mock(ElicitRequest.class)).block();
-
-				return Mono.just(mock(CallToolResult.class));
-			})
-			.build();
-
-		var server = McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").tools(tool).build();
-
-		try (
-				// Create client without elicitation capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
-
-			assertThat(client.initialize()).isNotNull();
-
-			try {
-				client.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class)
-					.hasMessage("Client must be configured with elicitation capabilities");
-			}
-		}
-		server.closeGracefully().block();
-	}
-
-	@Test
-	void testCreateElicitationSuccess() {
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-		mcpServer.closeGracefully().block();
-	}
-
-	@Test
-	void testCreateElicitationWithRequestTimeoutSuccess() {
-
-		// Client
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(3))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	@Test
-	void testCreateElicitationWithRequestTimeoutFail() {
-
-		// Client
-
-		Function elicitationHandler = request -> {
-			assertThat(request.message()).isNotEmpty();
-			assertThat(request.requestedSchema()).isNotNull();
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-		};
-
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
-		// Server
-
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
-
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				var elicitationRequest = ElicitRequest.builder()
-					.message("Test message")
-					.requestedSchema(
-							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
-					.build();
-
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.requestTimeout(Duration.ofSeconds(1))
-			.tools(tool)
-			.build();
-
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
-
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("Timeout");
-
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
-	}
-
-	// ---------------------------------------
-	// Roots Tests
-	// ---------------------------------------
-	@Test
-	void testRootsSuccess() {
-		List roots = List.of(new Root("uri1://", "root1"), new Root("uri2://", "root2"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-
-			// Remove a root
-			mcpClient.removeRoot(roots.get(0).uri());
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1)));
-			});
-
-			// Add a new root
-			var root3 = new Root("uri3://", "root3");
-			mcpClient.addRoot(root3);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
-			});
-
-			mcpServer.close();
-		}
-	}
-
-	@Test
-	void testRootsWithoutCapability() {
-
-		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				exchange.listRoots(); // try to list roots
-
-				return mock(CallToolResult.class);
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider).rootsChangeHandler((exchange, rootsUpdate) -> {
-		}).tools(tool).build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().build()).build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			// Attempt to list roots should fail
-			try {
-				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-			}
-			catch (McpError e) {
-				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
-			}
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testRootsNotificationWithEmptyRootsList() {
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(List.of()) // Empty roots list
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testRootsWithMultipleHandlers() {
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef1 = new AtomicReference<>();
-		AtomicReference> rootsRef2 = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef1.set(rootsUpdate))
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef2.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			assertThat(mcpClient.initialize()).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef1.get()).containsAll(roots);
-				assertThat(rootsRef2.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testRootsServerCloseWithActiveSubscription() {
-		List roots = List.of(new Root("uri1://", "root1"));
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.rootsChangeHandler((exchange, rootsUpdate) -> rootsRef.set(rootsUpdate))
-			.build();
-
-		try (var mcpClient = clientBuilder.capabilities(ClientCapabilities.builder().roots(true).build())
-			.roots(roots)
-			.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			mcpClient.rootsListChangedNotification();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(roots);
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Tools Tests
-	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
-	@Test
-	void testToolCallSuccess() {
-
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				assertThat(McpTestServletFilter.getThreadLocalValue()).as("blocking code exectuion should be offloaded")
-					.isNull();
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response).isEqualTo(callResponse);
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testToolCallImmediateExecution() {
-		McpServerFeatures.SyncToolSpecification tool1 = new McpServerFeatures.SyncToolSpecification(
-				new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema), (exchange, request) -> {
-					var threadLocalValue = McpTestServletFilter.getThreadLocalValue();
-					return CallToolResult.builder()
-						.addTextContent(threadLocalValue != null ? threadLocalValue : "")
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.immediateExecution(true)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			mcpClient.initialize();
-
-			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-
-			assertThat(response).isNotNull();
-			assertThat(response.content()).first()
-				.asInstanceOf(type(McpSchema.TextContent.class))
-				.extracting(McpSchema.TextContent::text)
-				.isEqualTo(McpTestServletFilter.THREAD_LOCAL_VALUE);
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testToolListChangeHandlingSuccess() {
-
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
-		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("tool1", "tool1 description", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-				// perform a blocking call to a remote service
-				String response = RestClient.create()
-					.get()
-					.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-					.retrieve()
-					.body(String.class);
-				assertThat(response).isNotBlank();
-				return callResponse;
-			})
-			.build();
-
-		AtomicReference> rootsRef = new AtomicReference<>();
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool1)
-			.build();
-
-		try (var mcpClient = clientBuilder.toolsChangeConsumer(toolsUpdate -> {
-			// perform a blocking call to a remote service
-			String response = RestClient.create()
-				.get()
-				.uri("https://raw.githubusercontent.com/modelcontextprotocol/java-sdk/refs/heads/main/README.md")
-				.retrieve()
-				.body(String.class);
-			assertThat(response).isNotBlank();
-			rootsRef.set(toolsUpdate);
-		}).build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			assertThat(rootsRef.get()).isNull();
-
-			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
-
-			mcpServer.notifyToolsListChanged();
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
-			});
-
-			// Remove a tool
-			mcpServer.removeTool("tool1");
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
-			});
-
-			// Add a new tool
-			McpServerFeatures.SyncToolSpecification tool2 = McpServerFeatures.SyncToolSpecification.builder()
-				.tool(new McpSchema.Tool("tool2", "tool2 description", emptyJsonSchema))
-				.callHandler((exchange, request) -> callResponse)
-				.build();
-
-			mcpServer.addTool(tool2);
-
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
-			});
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testInitialize() {
-		var mcpServer = McpServer.sync(mcpServerTransportProvider).build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Logging Tests
-	// ---------------------------------------
-	@Test
-	void testLoggingNotification() {
-		// Create a list to store received logging notifications
-		List receivedNotifications = new CopyOnWriteArrayList<>();
-
-		// Create server with a tool that sends logging notifications
-		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema))
-			.callHandler((exchange, request) -> {
-
-				// Create and send notifications with different levels
-
-				// This should be filtered out (DEBUG < NOTICE)
-				exchange
-					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-						.level(McpSchema.LoggingLevel.DEBUG)
-						.logger("test-logger")
-						.data("Debug message")
-						.build())
-					.block();
-
-				// This should be sent (NOTICE >= NOTICE)
-				exchange
-					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-						.level(McpSchema.LoggingLevel.NOTICE)
-						.logger("test-logger")
-						.data("Notice message")
-						.build())
-					.block();
-
-				// This should be sent (ERROR > NOTICE)
-				exchange
-					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-						.level(McpSchema.LoggingLevel.ERROR)
-						.logger("test-logger")
-						.data("Error message")
-						.build())
-					.block();
-
-				// This should be filtered out (INFO < NOTICE)
-				exchange
-					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-						.level(McpSchema.LoggingLevel.INFO)
-						.logger("test-logger")
-						.data("Another info message")
-						.build())
-					.block();
-
-				// This should be sent (ERROR >= NOTICE)
-				exchange
-					.loggingNotification(McpSchema.LoggingMessageNotification.builder()
-						.level(McpSchema.LoggingLevel.ERROR)
-						.logger("test-logger")
-						.data("Another error message")
-						.build())
-					.block();
-
-				return Mono.just(new CallToolResult("Logging test completed", false));
-			})
-			.build();
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
-			.tools(tool)
-			.build();
-		try (
-				// Create client with logging notification handler
-				var mcpClient = clientBuilder.loggingConsumer(notification -> {
-					receivedNotifications.add(notification);
-				}).build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Set minimum logging level to NOTICE
-			mcpClient.setLoggingLevel(McpSchema.LoggingLevel.NOTICE);
-
-			// Call the tool that sends logging notifications
-			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Logging test completed");
-
-			// Wait for notifications to be processed
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-
-				System.out.println("Received notifications: " + receivedNotifications);
-
-				// Should have received 3 notifications (1 NOTICE and 2 ERROR)
-				assertThat(receivedNotifications).hasSize(3);
-
-				Map notificationMap = receivedNotifications.stream()
-					.collect(Collectors.toMap(n -> n.data(), n -> n));
-
-				// First notification should be NOTICE level
-				assertThat(notificationMap.get("Notice message").level()).isEqualTo(McpSchema.LoggingLevel.NOTICE);
-				assertThat(notificationMap.get("Notice message").logger()).isEqualTo("test-logger");
-				assertThat(notificationMap.get("Notice message").data()).isEqualTo("Notice message");
-
-				// Second notification should be ERROR level
-				assertThat(notificationMap.get("Error message").level()).isEqualTo(McpSchema.LoggingLevel.ERROR);
-				assertThat(notificationMap.get("Error message").logger()).isEqualTo("test-logger");
-				assertThat(notificationMap.get("Error message").data()).isEqualTo("Error message");
-
-				// Third notification should be ERROR level
-				assertThat(notificationMap.get("Another error message").level())
-					.isEqualTo(McpSchema.LoggingLevel.ERROR);
-				assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
-				assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
-			});
-		}
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Progress Tests
-	// ---------------------------------------
-	@Test
-	void testProgressNotification() {
-		// Create a list to store received progress notifications
-		List receivedNotifications = new CopyOnWriteArrayList<>();
-
-		// Create server with a tool that sends progress notifications
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				McpSchema.Tool.builder()
-					.name("progress-test")
-					.description("Test progress notifications")
-					.inputSchema(emptyJsonSchema)
-					.build(),
-				null, (exchange, request) -> {
-
-					var progressToken = request.progressToken();
-
-					exchange
-						.progressNotification(
-								new McpSchema.ProgressNotification(progressToken, 0.1, 1.0, "Test progress 1/10"))
-						.block();
-
-					exchange
-						.progressNotification(
-								new McpSchema.ProgressNotification(progressToken, 0.5, 1.0, "Test progress 5/10"))
-						.block();
-
-					exchange
-						.progressNotification(
-								new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Test progress 10/10"))
-						.block();
-
-					return Mono.just(new CallToolResult("Progress test completed", false));
-				});
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
-			.tools(tool)
-			.build();
-
-		// Create client with progress notification handler
-		try (var mcpClient = clientBuilder.progressConsumer(receivedNotifications::add).build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call the tool that sends progress notifications
-			CallToolResult result = mcpClient.callTool(
-					new McpSchema.CallToolRequest("progress-test", Map.of(), Map.of("progressToken", "test-token")));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Progress test completed");
-
-			// Wait for notifications to be processed
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				// Should have received 3 notifications
-				assertThat(receivedNotifications).hasSize(3);
-
-				// Check the progress notifications
-				assertThat(receivedNotifications.stream().map(McpSchema.ProgressNotification::progressToken))
-					.containsExactlyInAnyOrder("test-token", "test-token", "test-token");
-				assertThat(receivedNotifications.stream().map(McpSchema.ProgressNotification::progress))
-					.containsExactlyInAnyOrder(0.1, 0.5, 1.0);
-			});
-		}
-		finally {
-			mcpServer.close();
-		}
-	}
-
-	// ---------------------------------------
-	// Ping Tests
-	// ---------------------------------------
-	@Test
-	void testPingSuccess() {
-		// Create server with a tool that uses ping functionality
-		AtomicReference executionOrder = new AtomicReference<>("");
-
-		McpServerFeatures.AsyncToolSpecification tool = new McpServerFeatures.AsyncToolSpecification(
-				new McpSchema.Tool("ping-async-test", "Test ping async behavior", emptyJsonSchema),
-				(exchange, request) -> {
-
-					executionOrder.set(executionOrder.get() + "1");
-
-					// Test async ping behavior
-					return exchange.ping().doOnNext(result -> {
-
-						assertThat(result).isNotNull();
-						// Ping should return an empty object or map
-						assertThat(result).isInstanceOf(Map.class);
-
-						executionOrder.set(executionOrder.get() + "2");
-						assertThat(result).isNotNull();
-					}).then(Mono.fromCallable(() -> {
-						executionOrder.set(executionOrder.get() + "3");
-						return new CallToolResult("Async ping test completed", false);
-					}));
-				});
-
-		var mcpServer = McpServer.async(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-
-			// Initialize client
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call the tool that tests ping async behavior
-			CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("ping-async-test", Map.of()));
-			assertThat(result).isNotNull();
-			assertThat(result.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content().get(0)).text()).isEqualTo("Async ping test completed");
-
-			// Verify execution order
-			assertThat(executionOrder.get()).isEqualTo("123");
-		}
-
-		mcpServer.close();
-	}
-
-	// ---------------------------------------
-	// Tool Structured Output Schema Tests
-	// ---------------------------------------
-	@Test
-	void testStructuredOutputValidationSuccess() {
-		// Create a tool with output schema
-		Map outputSchema = Map.of(
-				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
-						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
-				"required", List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					String expression = (String) request.getOrDefault("expression", "2 + 3");
-					double result = evaluateExpression(expression);
-					return CallToolResult.builder()
-						.structuredContent(
-								Map.of("result", result, "operation", expression, "timestamp", "2024-01-01T10:00:00Z"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Verify tool is listed with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call tool with valid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			assertThatJson(((McpSchema.TextContent) response.content().get(0)).text()).when(Option.IGNORING_ARRAY_ORDER)
-				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
-				.isObject()
-				.isEqualTo(json("""
-						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
-
-			// Verify structured content (may be null in sync server but validation still
-			// works)
-			if (response.structuredContent() != null) {
-				assertThat(response.structuredContent()).containsEntry("result", 5.0)
-					.containsEntry("operation", "2 + 3")
-					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
-			}
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testStructuredOutputValidationFailure() {
-
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
-				List.of("result", "operation"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return invalid structured output. Result should be number, missing
-					// operation
-					return CallToolResult.builder()
-						.addTextContent("Invalid calculation")
-						.structuredContent(Map.of("result", "not-a-number", "extra", "field"))
-						.build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool with invalid structured output
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).contains("Validation failed");
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testStructuredOutputMissingStructuredContent() {
-		// Create a tool with output schema
-		Map outputSchema = Map.of("type", "object", "properties",
-				Map.of("result", Map.of("type", "number")), "required", List.of("result"));
-
-		Tool calculatorTool = Tool.builder()
-			.name("calculator")
-			.description("Performs mathematical calculations")
-			.outputSchema(outputSchema)
-			.build();
-
-		McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(calculatorTool,
-				(exchange, request) -> {
-					// Return result without structured content but tool has output schema
-					return CallToolResult.builder().addTextContent("Calculation completed").build();
-				});
-
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tools(tool)
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Call tool that should return structured content but doesn't
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isTrue();
-			assertThat(response.content()).hasSize(1);
-			assertThat(response.content().get(0)).isInstanceOf(McpSchema.TextContent.class);
-
-			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
-			assertThat(errorMessage).isEqualTo(
-					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
-		}
-
-		mcpServer.close();
-	}
-
-	@Test
-	void testStructuredOutputRuntimeToolAddition() {
-		// Start server without tools
-		var mcpServer = McpServer.sync(mcpServerTransportProvider)
-			.serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.build();
-
-		try (var mcpClient = clientBuilder.build()) {
-			InitializeResult initResult = mcpClient.initialize();
-			assertThat(initResult).isNotNull();
-
-			// Initially no tools
-			assertThat(mcpClient.listTools().tools()).isEmpty();
-
-			// Add tool with output schema at runtime
-			Map outputSchema = Map.of("type", "object", "properties",
-					Map.of("message", Map.of("type", "string"), "count", Map.of("type", "integer")), "required",
-					List.of("message", "count"));
-
-			Tool dynamicTool = Tool.builder()
-				.name("dynamic-tool")
-				.description("Dynamically added tool")
-				.outputSchema(outputSchema)
-				.build();
-
-			McpServerFeatures.SyncToolSpecification toolSpec = new McpServerFeatures.SyncToolSpecification(dynamicTool,
-					(exchange, request) -> {
-						int count = (Integer) request.getOrDefault("count", 1);
-						return CallToolResult.builder()
-							.addTextContent("Dynamic tool executed " + count + " times")
-							.structuredContent(Map.of("message", "Dynamic execution", "count", count))
-							.build();
-					});
-
-			// Add tool to server
-			mcpServer.addTool(toolSpec);
-
-			// Wait for tool list change notification
-			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(mcpClient.listTools().tools()).hasSize(1);
-			});
-
-			// Verify tool was added with output schema
-			var toolsList = mcpClient.listTools();
-			assertThat(toolsList.tools()).hasSize(1);
-			assertThat(toolsList.tools().get(0).name()).isEqualTo("dynamic-tool");
-			// Note: outputSchema might be null in sync server, but validation still works
-
-			// Call dynamically added tool
-			CallToolResult response = mcpClient
-				.callTool(new McpSchema.CallToolRequest("dynamic-tool", Map.of("count", 3)));
-
-			assertThat(response).isNotNull();
-			assertThat(response.isError()).isFalse();
-			assertThat(response.structuredContent()).containsEntry("message", "Dynamic execution")
-				.containsEntry("count", 3);
-		}
-
-		mcpServer.close();
-	}
-
-	private double evaluateExpression(String expression) {
-		// Simple expression evaluator for testing
-		return switch (expression) {
-			case "2 + 3" -> 5.0;
-			case "10 * 2" -> 20.0;
-			case "7 + 8" -> 15.0;
-			case "5 + 3" -> 8.0;
-			default -> 0.0;
-		};
-	}
-
-}

From eb427add7952bfdf08fcabc7d8aedc633e45bcf9 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Sat, 9 Aug 2025 18:41:01 +0100
Subject: [PATCH 047/125] refactor: improve integration tests stability
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace inline StepVerifier assertions with AtomicReference pattern for better testability
- Add assertWith() usage for cleaner assertion blocks in async tests
- Simplify reactive chains using doOnNext() and thenReturn() patterns
- Remove unnecessary Thread.sleep() from elicitation handler
- Improve variable naming (rootsRef → toolsRef) for clarity
- Update timeout error message assertions to be more specific
- Clean up code formatting and remove redundant comments

Signed-off-by: Christian Tzolov 
---
 .../WebMvcStreamableIntegrationTests.java     |   3 -
 ...stractMcpClientServerIntegrationTests.java | 134 ++++++++--------
 ...stractMcpClientServerIntegrationTests.java | 143 ++++++++----------
 3 files changed, 126 insertions(+), 154 deletions(-)

diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
index 84862f27e..800065915 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -11,8 +11,6 @@
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -29,7 +27,6 @@
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
 import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
-import io.modelcontextprotocol.spec.McpSchema;
 import reactor.core.scheduler.Schedulers;
 
 class WebMvcStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index ef6730a7c..26fd71d2b 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -8,6 +8,7 @@
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertWith;
 import static org.awaitility.Awaitility.await;
 import static org.mockito.Mockito.mock;
 
@@ -144,6 +145,8 @@ void testCreateMessageSuccess(String clientType) {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
+		AtomicReference samplingResult = new AtomicReference<>();
+
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
@@ -159,37 +162,35 @@ void testCreateMessageSuccess(String clientType) {
 						.build())
 					.build();
 
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createMessage(createMessageRequest)
+					.doOnNext(samplingResult::set)
+					.thenReturn(callResponse);
 			})
 			.build();
 
-		//@formatter:off		
-		var mcpServer = prepareAsyncServerBuilder()
-				.serverInfo("test-server", "1.0.0")
-				.tools(tool)
-				.build();
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
 
-		try (
-			var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-				.capabilities(ClientCapabilities.builder().sampling().build())
-				.sampling(samplingHandler)
-				.build()) {//@formatter:on
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
 
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 
 			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
-			assertThat(response).isNotNull().isEqualTo(callResponse);
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+
+			assertWith(samplingResult.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.role()).isEqualTo(Role.USER);
+				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+				assertThat(result.model()).isEqualTo("MockModelName");
+				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+			});
 		}
 		mcpServer.close();
 	}
@@ -225,6 +226,8 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
+		AtomicReference samplingResult = new AtomicReference<>();
+
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
@@ -240,16 +243,9 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 						.build())
 					.build();
 
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createMessage(createMessageRequest)
+					.doOnNext(samplingResult::set)
+					.thenReturn(callResponse);
 			})
 			.build();
 
@@ -266,6 +262,15 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 		assertThat(response).isNotNull();
 		assertThat(response).isEqualTo(callResponse);
 
+		assertWith(samplingResult.get(), result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.role()).isEqualTo(Role.USER);
+			assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+			assertThat(result.model()).isEqualTo("MockModelName");
+			assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+		});
+
 		mcpClient.close();
 		mcpServer.close();
 	}
@@ -312,16 +317,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 						.build())
 					.build();
 
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createMessage(createMessageRequest).thenReturn(callResponse);
 			})
 			.build();
 
@@ -335,7 +331,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 
 		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
 			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("Timeout");
+		}).withMessageContaining("1000ms");
 
 		mcpClient.close();
 		mcpServer.close();
@@ -352,19 +348,14 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
-			.callHandler((exchange, request) -> {
-
-				exchange.createElicitation(mock(McpSchema.ElicitRequest.class)).block();
-
-				return Mono.just(mock(CallToolResult.class));
-			})
+			.callHandler((exchange, request) -> exchange.createElicitation(mock(ElicitRequest.class))
+				.then(Mono.just(mock(CallToolResult.class))))
 			.build();
 
 		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
 
-		try (
-				// Create client without elicitation capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
+		// Create client without elicitation capabilities
+		try (var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
 
 			assertThat(client.initialize()).isNotNull();
 
@@ -440,17 +431,10 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
-		Function elicitationHandler = request -> {
+		Function elicitationHandler = request -> {
 			assertThat(request.message()).isNotEmpty();
 			assertThat(request.requestedSchema()).isNotNull();
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
-					Map.of("message", request.message()));
+			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
 		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
@@ -461,6 +445,8 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
+		AtomicReference resultRef = new AtomicReference<>();
+
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
@@ -471,13 +457,9 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
 					.build();
 
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createElicitation(elicitationRequest)
+					.doOnNext(resultRef::set)
+					.then(Mono.just(callResponse));
 			})
 			.build();
 
@@ -493,6 +475,11 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 
 		assertThat(response).isNotNull();
 		assertThat(response).isEqualTo(callResponse);
+		assertWith(resultRef.get(), result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+			assertThat(result.content().get("message")).isEqualTo("Test message");
+		});
 
 		mcpClient.closeGracefully();
 		mcpServer.closeGracefully().block();
@@ -870,7 +857,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 			})
 			.build();
 
-		AtomicReference> rootsRef = new AtomicReference<>();
+		AtomicReference> toolsRef = new AtomicReference<>();
 
 		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(tool1)
@@ -887,32 +874,31 @@ void testToolListChangeHandlingSuccess(String clientType) {
 						.build(), HttpResponse.BodyHandlers.ofString());
 				String responseBody = response.body();
 				assertThat(responseBody).isNotBlank();
+				toolsRef.set(toolsUpdate);
 			}
 			catch (Exception e) {
 				e.printStackTrace();
 			}
-
-			rootsRef.set(toolsUpdate);
 		}).build()) {
 
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 
-			assertThat(rootsRef.get()).isNull();
+			assertThat(toolsRef.get()).isNull();
 
 			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
 
 			mcpServer.notifyToolsListChanged();
 
 			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
+				assertThat(toolsRef.get()).containsAll(List.of(tool1.tool()));
 			});
 
 			// Remove a tool
 			mcpServer.removeTool("tool1");
 
 			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
+				assertThat(toolsRef.get()).isEmpty();
 			});
 
 			// Add a new tool
@@ -928,7 +914,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 			mcpServer.addTool(tool2);
 
 			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
+				assertThat(toolsRef.get()).containsAll(List.of(tool2.tool()));
 			});
 		}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index 28b353d32..e2adb340c 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -8,6 +8,7 @@
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertWith;
 import static org.awaitility.Awaitility.await;
 import static org.mockito.Mockito.mock;
 
@@ -43,6 +44,9 @@
 import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
 import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
 import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
+import io.modelcontextprotocol.spec.McpSchema.Prompt;
+import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import io.modelcontextprotocol.spec.McpSchema.Role;
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
@@ -137,6 +141,8 @@ void testCreateMessageSuccess(String clientType) {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
+		AtomicReference samplingResult = new AtomicReference<>();
+
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
@@ -152,37 +158,35 @@ void testCreateMessageSuccess(String clientType) {
 						.build())
 					.build();
 
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createMessage(createMessageRequest)
+					.doOnNext(samplingResult::set)
+					.thenReturn(callResponse);
 			})
 			.build();
 
-		//@formatter:off		
-		var mcpServer = prepareAsyncServerBuilder()
-				.serverInfo("test-server", "1.0.0")
-				.tools(tool)
-				.build();
+		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
 
-		try (
-			var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-				.capabilities(ClientCapabilities.builder().sampling().build())
-				.sampling(samplingHandler)
-				.build()) {//@formatter:on
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
 
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 
 			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
-			assertThat(response).isNotNull().isEqualTo(callResponse);
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+
+			assertWith(samplingResult.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.role()).isEqualTo(Role.USER);
+				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+				assertThat(result.model()).isEqualTo("MockModelName");
+				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+			});
 		}
 		mcpServer.close();
 	}
@@ -218,6 +222,8 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
+		AtomicReference samplingResult = new AtomicReference<>();
+
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
@@ -233,16 +239,9 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 						.build())
 					.build();
 
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createMessage(createMessageRequest)
+					.doOnNext(samplingResult::set)
+					.thenReturn(callResponse);
 			})
 			.build();
 
@@ -259,6 +258,15 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 		assertThat(response).isNotNull();
 		assertThat(response).isEqualTo(callResponse);
 
+		assertWith(samplingResult.get(), result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.role()).isEqualTo(Role.USER);
+			assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+			assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+			assertThat(result.model()).isEqualTo("MockModelName");
+			assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+		});
+
 		mcpClient.close();
 		mcpServer.close();
 	}
@@ -305,16 +313,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 						.build())
 					.build();
 
-				StepVerifier.create(exchange.createMessage(createMessageRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.role()).isEqualTo(Role.USER);
-					assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-					assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-					assertThat(result.model()).isEqualTo("MockModelName");
-					assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createMessage(createMessageRequest).thenReturn(callResponse);
 			})
 			.build();
 
@@ -328,7 +327,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 
 		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
 			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("Timeout");
+		}).withMessageContaining("1000ms");
 
 		mcpClient.close();
 		mcpServer.close();
@@ -345,19 +344,14 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
-			.callHandler((exchange, request) -> {
-
-				exchange.createElicitation(mock(McpSchema.ElicitRequest.class)).block();
-
-				return Mono.just(mock(CallToolResult.class));
-			})
+			.callHandler((exchange, request) -> exchange.createElicitation(mock(ElicitRequest.class))
+				.then(Mono.just(mock(CallToolResult.class))))
 			.build();
 
 		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").tools(tool).build();
 
-		try (
-				// Create client without elicitation capabilities
-				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
+		// Create client without elicitation capabilities
+		try (var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0")).build()) {
 
 			assertThat(client.initialize()).isNotNull();
 
@@ -433,17 +427,10 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
-		Function elicitationHandler = request -> {
+		Function elicitationHandler = request -> {
 			assertThat(request.message()).isNotEmpty();
 			assertThat(request.requestedSchema()).isNotNull();
-			try {
-				TimeUnit.SECONDS.sleep(2);
-			}
-			catch (InterruptedException e) {
-				throw new RuntimeException(e);
-			}
-			return new McpSchema.ElicitResult(McpSchema.ElicitResult.Action.ACCEPT,
-					Map.of("message", request.message()));
+			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
 		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
@@ -454,6 +441,8 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
+		AtomicReference resultRef = new AtomicReference<>();
+
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
@@ -464,13 +453,9 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
 					.build();
 
-				StepVerifier.create(exchange.createElicitation(elicitationRequest)).consumeNextWith(result -> {
-					assertThat(result).isNotNull();
-					assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
-					assertThat(result.content().get("message")).isEqualTo("Test message");
-				}).verifyComplete();
-
-				return Mono.just(callResponse);
+				return exchange.createElicitation(elicitationRequest)
+					.doOnNext(resultRef::set)
+					.then(Mono.just(callResponse));
 			})
 			.build();
 
@@ -486,6 +471,11 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 
 		assertThat(response).isNotNull();
 		assertThat(response).isEqualTo(callResponse);
+		assertWith(resultRef.get(), result -> {
+			assertThat(result).isNotNull();
+			assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+			assertThat(result.content().get("message")).isEqualTo("Test message");
+		});
 
 		mcpClient.closeGracefully();
 		mcpServer.closeGracefully().block();
@@ -863,7 +853,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 			})
 			.build();
 
-		AtomicReference> rootsRef = new AtomicReference<>();
+		AtomicReference> toolsRef = new AtomicReference<>();
 
 		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(tool1)
@@ -880,32 +870,31 @@ void testToolListChangeHandlingSuccess(String clientType) {
 						.build(), HttpResponse.BodyHandlers.ofString());
 				String responseBody = response.body();
 				assertThat(responseBody).isNotBlank();
+				toolsRef.set(toolsUpdate);
 			}
 			catch (Exception e) {
 				e.printStackTrace();
 			}
-
-			rootsRef.set(toolsUpdate);
 		}).build()) {
 
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 
-			assertThat(rootsRef.get()).isNull();
+			assertThat(toolsRef.get()).isNull();
 
 			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
 
 			mcpServer.notifyToolsListChanged();
 
 			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool1.tool()));
+				assertThat(toolsRef.get()).containsAll(List.of(tool1.tool()));
 			});
 
 			// Remove a tool
 			mcpServer.removeTool("tool1");
 
 			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).isEmpty();
+				assertThat(toolsRef.get()).isEmpty();
 			});
 
 			// Add a new tool
@@ -921,7 +910,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 			mcpServer.addTool(tool2);
 
 			await().atMost(Duration.ofSeconds(5)).untilAsserted(() -> {
-				assertThat(rootsRef.get()).containsAll(List.of(tool2.tool()));
+				assertThat(toolsRef.get()).containsAll(List.of(tool2.tool()));
 			});
 		}
 
@@ -1184,8 +1173,8 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 
 		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().completions().build())
 			.prompts(new McpServerFeatures.SyncPromptSpecification(
-					new McpSchema.Prompt("code_review", "Code review", "this is code review prompt",
-							List.of(new McpSchema.PromptArgument("language", "Language", "string", false))),
+					new Prompt("code_review", "Code review", "this is code review prompt",
+							List.of(new PromptArgument("language", "Language", "string", false))),
 					(mcpSyncServerExchange, getPromptRequest) -> null))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
 					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
@@ -1197,7 +1186,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 			assertThat(initResult).isNotNull();
 
 			CompleteRequest request = new CompleteRequest(
-					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"),
+					new PromptReference("ref/prompt", "code_review", "Code review"),
 					new CompleteRequest.CompleteArgument("language", "py"));
 
 			CompleteResult result = mcpClient.completeCompletion(request);

From 6c38f3763706b7adb15a17831ff7bada5f718897 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 7 Aug 2025 18:35:50 +0100
Subject: [PATCH 048/125] fix: improve streamable HTTP session reinitialization
 (#459)

Implements the MCP spec guidelines for streamable HTTP (re)initialization:
- Server MAY terminate session and MUST respond with HTTP 404 for terminated session IDs
- Client MUST start new session when receiving HTTP 404 for requests with session ID

Changes:
- Replace generic McpError with McpTransportException for transport-layer errors
- Only throw McpTransportSessionNotFoundException when session ID is present in request
  (per spec: 404 with session ID means session terminated, without means general error)
- Enhance error messages with more context (status codes, response events)
- Use RuntimeException for non-transport specific SSE endpoint failures
- Ensure consistent error handling across HTTP client transports

- Improve error handling with standard Java exceptions.
  Replace generic McpError with appropriate standard exceptions:
  - Use IllegalArgumentException for invalid input parameters
  - Use IllegalStateException for state-related issues
  - Use RuntimeException wrapper for initialization failures
  - Use McpError.builder() with proper error codes for protocol errors

Fixes #459

Signed-off-by: Christian Tzolov 
---
 .../WebClientStreamableHttpTransport.java     |  33 +-
 .../transport/WebFluxSseClientTransport.java  |   5 +-
 .../WebFluxSseIntegrationTests.java           |   2 +
 .../WebFluxStatelessIntegrationTests.java     |   2 +
 .../WebFluxStreamableIntegrationTests.java    |   2 +
 ...eamableHttpTransportErrorHandlingTest.java | 404 ++++++++++++++++++
 .../server/WebMvcSseIntegrationTests.java     |   2 +
 .../WebMvcStatelessIntegrationTests.java      |   2 +
 .../WebMvcStreamableIntegrationTests.java     |   2 +
 .../client/AbstractMcpAsyncClientTests.java   |   5 +-
 .../client/LifecycleInitializer.java          |  10 +-
 .../client/McpAsyncClient.java                |  30 +-
 .../HttpClientSseClientTransport.java         |  10 +-
 .../HttpClientStreamableHttpTransport.java    |  87 ++--
 .../client/transport/ResponseSubscribers.java |   5 +-
 .../spec/McpTransportException.java           |  38 ++
 .../client/AbstractMcpAsyncClientTests.java   |   5 +-
 .../client/LifecycleInitializerTests.java     |   7 +-
 .../McpAsyncClientResponseHandlerTests.java   |   5 +-
 .../client/McpClientProtocolVersionTests.java |   2 +-
 ...eamableHttpTransportErrorHandlingTest.java | 345 +++++++++++++++
 .../HttpServletSseIntegrationTests.java       |   2 +
 .../HttpServletStatelessIntegrationTests.java |   2 +
 ...HttpServletStreamableIntegrationTests.java |   2 +
 .../server/McpCompletionTests.java            |  36 +-
 25 files changed, 955 insertions(+), 90 deletions(-)
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 6d8e82f51..853aed2bf 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -31,6 +31,7 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportException;
 import io.modelcontextprotocol.spec.McpTransportSession;
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.spec.McpTransportStream;
@@ -70,6 +71,8 @@
  */
 public class WebClientStreamableHttpTransport implements McpClientTransport {
 
+	private static final String MISSING_SESSION_ID = "[missing_session_id]";
+
 	private static final Logger logger = LoggerFactory.getLogger(WebClientStreamableHttpTransport.class);
 
 	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_03_26;
@@ -221,8 +224,13 @@ else if (isNotAllowed(response)) {
 						return Flux.empty();
 					}
 					else if (isNotFound(response)) {
-						String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
-						return mcpSessionNotFoundError(sessionIdRepresentation);
+						if (transportSession.sessionId().isPresent()) {
+							String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
+							return mcpSessionNotFoundError(sessionIdRepresentation);
+						}
+						else {
+							return this.extractError(response, MISSING_SESSION_ID);
+						}
 					}
 					else {
 						return response.createError().doOnError(e -> {
@@ -318,10 +326,10 @@ else if (mediaType.isCompatibleWith(MediaType.APPLICATION_JSON)) {
 						}
 					}
 					else {
-						if (isNotFound(response)) {
+						if (isNotFound(response) && !sessionRepresentation.equals(MISSING_SESSION_ID)) {
 							return mcpSessionNotFoundError(sessionRepresentation);
 						}
-						return extractError(response, sessionRepresentation);
+						return this.extractError(response, sessionRepresentation);
 					}
 				})
 				.flatMap(jsonRpcMessage -> this.handler.get().apply(Mono.just(jsonRpcMessage)))
@@ -362,10 +370,10 @@ private Flux extractError(ClientResponse response, Str
 						McpSchema.JSONRPCResponse.class);
 				jsonRpcError = jsonRpcResponse.error();
 				toPropagate = jsonRpcError != null ? new McpError(jsonRpcError)
-						: new McpError("Can't parse the jsonResponse " + jsonRpcResponse);
+						: new McpTransportException("Can't parse the jsonResponse " + jsonRpcResponse);
 			}
 			catch (IOException ex) {
-				toPropagate = new RuntimeException("Sending request failed", e);
+				toPropagate = new McpTransportException("Sending request failed, " + e.getMessage(), e);
 				logger.debug("Received content together with {} HTTP code response: {}", response.statusCode(), body);
 			}
 
@@ -374,7 +382,11 @@ private Flux extractError(ClientResponse response, Str
 			// invalidate the session
 			// https://github.com/modelcontextprotocol/typescript-sdk/issues/389
 			if (responseException.getStatusCode().isSameCodeAs(HttpStatus.BAD_REQUEST)) {
-				return Mono.error(new McpTransportSessionNotFoundException(sessionRepresentation, toPropagate));
+				if (!sessionRepresentation.equals(MISSING_SESSION_ID)) {
+					return Mono.error(new McpTransportSessionNotFoundException(sessionRepresentation, toPropagate));
+				}
+				return Mono.error(new McpTransportException("Received 400 BAD REQUEST for session "
+						+ sessionRepresentation + ". " + toPropagate.getMessage(), toPropagate));
 			}
 			return Mono.error(toPropagate);
 		}).flux();
@@ -403,7 +415,7 @@ private static boolean isEventStream(ClientResponse response) {
 	}
 
 	private static String sessionIdOrPlaceholder(McpTransportSession transportSession) {
-		return transportSession.sessionId().orElse("[missing_session_id]");
+		return transportSession.sessionId().orElse(MISSING_SESSION_ID);
 	}
 
 	private Flux directResponseFlux(McpSchema.JSONRPCMessage sentMessage,
@@ -421,8 +433,7 @@ private Flux directResponseFlux(McpSchema.JSONRPCMessa
 				}
 			}
 			catch (IOException e) {
-				// TODO: this should be a McpTransportError
-				s.error(e);
+				s.error(new McpTransportException(e));
 			}
 		}).flatMapIterable(Function.identity());
 	}
@@ -449,7 +460,7 @@ private Tuple2, Iterable> parse(Serve
 				return Tuples.of(Optional.ofNullable(event.id()), List.of(message));
 			}
 			catch (IOException ioException) {
-				throw new McpError("Error parsing JSON-RPC message: " + event.data());
+				throw new McpTransportException("Error parsing JSON-RPC message: " + event.data(), ioException);
 			}
 		}
 		else {
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
index 75caebef0..51d21d18b 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
@@ -14,7 +14,6 @@
 
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
 import io.modelcontextprotocol.spec.ProtocolVersions;
@@ -197,8 +196,6 @@ public List protocolVersions() {
 	 * @param handler a function that processes incoming JSON-RPC messages and returns
 	 * responses
 	 * @return a Mono that completes when the connection is fully established
-	 * @throws McpError if there's an error processing SSE events or if an unrecognized
-	 * event type is received
 	 */
 	@Override
 	public Mono connect(Function, Mono> handler) {
@@ -215,7 +212,7 @@ public Mono connect(Function, Mono> h
 				else {
 					// TODO: clarify with the spec if multiple events can be
 					// received
-					s.error(new McpError("Failed to handle SSE endpoint event"));
+					s.error(new RuntimeException("Failed to handle SSE endpoint event"));
 				}
 			}
 			else if (MESSAGE_EVENT_TYPE.equals(event.event())) {
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index a1f1a8947..6140fe489 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -8,6 +8,7 @@
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -26,6 +27,7 @@
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
 
+@Timeout(15)
 class WebFluxSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
index 302c58c5f..5516e55b7 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
@@ -8,6 +8,7 @@
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -26,6 +27,7 @@
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
 
+@Timeout(15)
 class WebFluxStatelessIntegrationTests extends AbstractStatelessIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
index 616c6dcf8..9eba0e57c 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -8,6 +8,7 @@
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -26,6 +27,7 @@
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
 
+@Timeout(15)
 class WebFluxStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java
new file mode 100644
index 000000000..cdbb97e17
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java
@@ -0,0 +1,404 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.timeout;
+import static org.mockito.Mockito.verify;
+
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.time.Duration;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+import org.springframework.web.reactive.function.client.WebClient;
+
+import com.sun.net.httpserver.HttpServer;
+
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.spec.HttpHeaders;
+import io.modelcontextprotocol.spec.McpClientTransport;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportException;
+import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
+import io.modelcontextprotocol.spec.ProtocolVersions;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+/**
+ * Tests for error handling in WebClientStreamableHttpTransport. Addresses concurrency
+ * issues with proper Reactor patterns.
+ *
+ * @author Christian Tzolov
+ */
+@Timeout(15)
+public class WebClientStreamableHttpTransportErrorHandlingTest {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String HOST = "http://localhost:" + PORT;
+
+	private HttpServer server;
+
+	private AtomicReference serverResponseStatus = new AtomicReference<>(200);
+
+	private AtomicReference currentServerSessionId = new AtomicReference<>(null);
+
+	private AtomicReference lastReceivedSessionId = new AtomicReference<>(null);
+
+	private McpClientTransport transport;
+
+	// Initialize latches for proper request synchronization
+	CountDownLatch firstRequestLatch;
+
+	CountDownLatch secondRequestLatch;
+
+	CountDownLatch getRequestLatch;
+
+	@BeforeEach
+	void startServer() throws IOException {
+
+		// Initialize latches for proper synchronization
+		firstRequestLatch = new CountDownLatch(1);
+		secondRequestLatch = new CountDownLatch(1);
+		getRequestLatch = new CountDownLatch(1);
+
+		server = HttpServer.create(new InetSocketAddress(PORT), 0);
+
+		// Configure the /mcp endpoint with dynamic response
+		server.createContext("/mcp", exchange -> {
+			String method = exchange.getRequestMethod();
+
+			if ("GET".equals(method)) {
+				// This is the SSE connection attempt after session establishment
+				getRequestLatch.countDown();
+				// Return 405 Method Not Allowed to indicate SSE not supported
+				exchange.sendResponseHeaders(405, 0);
+				exchange.close();
+				return;
+			}
+
+			String requestSessionId = exchange.getRequestHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+			lastReceivedSessionId.set(requestSessionId);
+
+			int status = serverResponseStatus.get();
+
+			// Track which request this is
+			if (firstRequestLatch.getCount() > 0) {
+				// // First request - should have no session ID
+				firstRequestLatch.countDown();
+			}
+			else if (secondRequestLatch.getCount() > 0) {
+				// Second request - should have session ID
+				secondRequestLatch.countDown();
+			}
+
+			exchange.getResponseHeaders().set("Content-Type", "application/json");
+
+			// Don't include session ID in 404 and 400 responses - the implementation
+			// checks if the transport has a session stored locally
+			String responseSessionId = currentServerSessionId.get();
+			if (responseSessionId != null && status == 200) {
+				exchange.getResponseHeaders().set(HttpHeaders.MCP_SESSION_ID, responseSessionId);
+			}
+			if (status == 200) {
+				String response = "{\"jsonrpc\":\"2.0\",\"result\":{},\"id\":\"test-id\"}";
+				exchange.sendResponseHeaders(200, response.length());
+				exchange.getResponseBody().write(response.getBytes());
+			}
+			else {
+				exchange.sendResponseHeaders(status, 0);
+			}
+			exchange.close();
+		});
+
+		server.setExecutor(null);
+		server.start();
+
+		transport = WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl(HOST)).build();
+	}
+
+	@AfterEach
+	void stopServer() {
+		if (server != null) {
+			server.stop(0);
+		}
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	/**
+	 * Test that 404 response WITHOUT session ID throws McpTransportException (not
+	 * SessionNotFoundException)
+	 */
+	@Test
+	void test404WithoutSessionId() {
+		serverResponseStatus.set(404);
+		currentServerSessionId.set(null); // No session ID in response
+
+		var testMessage = createTestMessage();
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMatches(throwable -> throwable instanceof McpTransportException
+					&& throwable.getMessage().contains("Not Found") && throwable.getMessage().contains("404")
+					&& !(throwable instanceof McpTransportSessionNotFoundException))
+			.verify(Duration.ofSeconds(5));
+	}
+
+	/**
+	 * Test that 404 response WITH session ID throws McpTransportSessionNotFoundException
+	 * Fixed version using proper async coordination
+	 */
+	@Test
+	void test404WithSessionId() throws InterruptedException {
+		// First establish a session
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("test-session-123");
+
+		// Set up exception handler to verify session invalidation
+		@SuppressWarnings("unchecked")
+		Consumer exceptionHandler = mock(Consumer.class);
+		transport.setExceptionHandler(exceptionHandler);
+
+		// Connect with handler
+		StepVerifier.create(transport.connect(msg -> msg)).verifyComplete();
+
+		// Send initial message to establish session
+		var testMessage = createTestMessage();
+
+		// Send first message to establish session
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// Wait for first request to complete
+		assertThat(firstRequestLatch.await(5, TimeUnit.SECONDS)).isTrue();
+
+		// Wait for the GET request (SSE connection attempt) to complete
+		assertThat(getRequestLatch.await(5, TimeUnit.SECONDS)).isTrue();
+
+		// Now return 404 for next request
+		serverResponseStatus.set(404);
+
+		// Use delaySubscription to ensure session is fully processed before next
+		// request
+		StepVerifier.create(Mono.delay(Duration.ofMillis(200)).then(transport.sendMessage(testMessage)))
+			.expectError(McpTransportSessionNotFoundException.class)
+			.verify(Duration.ofSeconds(5));
+
+		// Wait for second request to be made
+		assertThat(secondRequestLatch.await(5, TimeUnit.SECONDS)).isTrue();
+
+		// Verify the second request included the session ID
+		assertThat(lastReceivedSessionId.get()).isEqualTo("test-session-123");
+
+		// Verify exception handler was called with SessionNotFoundException using
+		// timeout
+		verify(exceptionHandler, timeout(5000)).accept(any(McpTransportSessionNotFoundException.class));
+	}
+
+	/**
+	 * Test that 400 response WITHOUT session ID throws McpTransportException (not
+	 * SessionNotFoundException)
+	 */
+	@Test
+	void test400WithoutSessionId() {
+		serverResponseStatus.set(400);
+		currentServerSessionId.set(null); // No session ID
+
+		var testMessage = createTestMessage();
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMatches(throwable -> throwable instanceof McpTransportException
+					&& throwable.getMessage().contains("Bad Request") && throwable.getMessage().contains("400")
+					&& !(throwable instanceof McpTransportSessionNotFoundException))
+			.verify(Duration.ofSeconds(5));
+	}
+
+	/**
+	 * Test that 400 response WITH session ID throws McpTransportSessionNotFoundException
+	 * Fixed version using proper async coordination
+	 */
+	@Test
+	void test400WithSessionId() throws InterruptedException {
+
+		// First establish a session
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("test-session-456");
+
+		// Set up exception handler
+		@SuppressWarnings("unchecked")
+		Consumer exceptionHandler = mock(Consumer.class);
+		transport.setExceptionHandler(exceptionHandler);
+
+		// Connect with handler
+		StepVerifier.create(transport.connect(msg -> msg)).verifyComplete();
+
+		// Send initial message to establish session
+		var testMessage = createTestMessage();
+
+		// Send first message to establish session
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// Wait for first request to complete
+		boolean firstCompleted = firstRequestLatch.await(5, TimeUnit.SECONDS);
+		assertThat(firstCompleted).isTrue();
+
+		// Wait for the GET request (SSE connection attempt) to complete
+		boolean getCompleted = getRequestLatch.await(5, TimeUnit.SECONDS);
+		assertThat(getCompleted).isTrue();
+
+		// Now return 400 for next request (simulating unknown session ID)
+		serverResponseStatus.set(400);
+
+		// Use delaySubscription to ensure session is fully processed before next
+		// request
+		StepVerifier.create(Mono.delay(Duration.ofMillis(200)).then(transport.sendMessage(testMessage)))
+			.expectError(McpTransportSessionNotFoundException.class)
+			.verify(Duration.ofSeconds(5));
+
+		// Wait for second request to be made
+		boolean secondCompleted = secondRequestLatch.await(5, TimeUnit.SECONDS);
+		assertThat(secondCompleted).isTrue();
+
+		// Verify the second request included the session ID
+		assertThat(lastReceivedSessionId.get()).isEqualTo("test-session-456");
+
+		// Verify exception handler was called with timeout
+		verify(exceptionHandler, timeout(5000)).accept(any(McpTransportSessionNotFoundException.class));
+	}
+
+	/**
+	 * Test session recovery after SessionNotFoundException Fixed version using reactive
+	 * patterns and proper synchronization
+	 */
+	@Test
+	void testSessionRecoveryAfter404() {
+		// First establish a session
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("session-1");
+
+		// Send initial message to establish session
+		var testMessage = createTestMessage();
+
+		// Use Mono.defer to ensure proper sequencing
+		Mono establishSession = transport.sendMessage(testMessage).then(Mono.defer(() -> {
+			// Simulate session loss - return 404
+			serverResponseStatus.set(404);
+			return transport.sendMessage(testMessage).onErrorResume(McpTransportSessionNotFoundException.class, e -> {
+				// Expected error, continue with recovery
+				return Mono.empty();
+			});
+		})).then(Mono.defer(() -> {
+			// Now server is back with new session
+			serverResponseStatus.set(200);
+			currentServerSessionId.set("session-2");
+			lastReceivedSessionId.set(null); // Reset to verify new session
+
+			// Should be able to establish new session
+			return transport.sendMessage(testMessage);
+		})).then(Mono.defer(() -> {
+			// Verify no session ID was sent (since old session was invalidated)
+			assertThat(lastReceivedSessionId.get()).isNull();
+
+			// Next request should use the new session ID
+			return transport.sendMessage(testMessage);
+		})).doOnSuccess(v -> {
+			// Session ID should now be sent with requests
+			assertThat(lastReceivedSessionId.get()).isEqualTo("session-2");
+		});
+
+		StepVerifier.create(establishSession).verifyComplete();
+	}
+
+	/**
+	 * Test that reconnect (GET request) also properly handles 404/400 errors Fixed
+	 * version with proper async handling
+	 */
+	@Test
+	void testReconnectErrorHandling() throws InterruptedException {
+		// Initialize latch for SSE connection
+		CountDownLatch sseConnectionLatch = new CountDownLatch(1);
+
+		// Set up SSE endpoint for GET requests
+		server.createContext("/mcp-sse", exchange -> {
+			String method = exchange.getRequestMethod();
+			String requestSessionId = exchange.getRequestHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+
+			if ("GET".equals(method)) {
+				sseConnectionLatch.countDown();
+				int status = serverResponseStatus.get();
+
+				if (status == 404 && requestSessionId != null) {
+					// 404 with session ID - should trigger SessionNotFoundException
+					exchange.sendResponseHeaders(404, 0);
+				}
+				else if (status == 404) {
+					// 404 without session ID - should trigger McpTransportException
+					exchange.sendResponseHeaders(404, 0);
+				}
+				else {
+					// Normal SSE response
+					exchange.getResponseHeaders().set("Content-Type", "text/event-stream");
+					exchange.sendResponseHeaders(200, 0);
+					// Send a test SSE event
+					String sseData = "event: message\ndata: {\"jsonrpc\":\"2.0\",\"method\":\"test\",\"params\":{}}\n\n";
+					exchange.getResponseBody().write(sseData.getBytes());
+				}
+			}
+			else {
+				// POST request handling
+				exchange.getResponseHeaders().set("Content-Type", "application/json");
+				String responseSessionId = currentServerSessionId.get();
+				if (responseSessionId != null) {
+					exchange.getResponseHeaders().set(HttpHeaders.MCP_SESSION_ID, responseSessionId);
+				}
+				String response = "{\"jsonrpc\":\"2.0\",\"result\":{},\"id\":\"test-id\"}";
+				exchange.sendResponseHeaders(200, response.length());
+				exchange.getResponseBody().write(response.getBytes());
+			}
+			exchange.close();
+		});
+
+		// Test with session ID - should get SessionNotFoundException
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("sse-session-1");
+
+		var transport = WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl(HOST))
+			.endpoint("/mcp-sse")
+			.openConnectionOnStartup(true) // This will trigger GET request on connect
+			.build();
+
+		// First connect successfully
+		StepVerifier.create(transport.connect(msg -> msg)).verifyComplete();
+
+		// Wait for SSE connection to be established
+		boolean connected = sseConnectionLatch.await(5, TimeUnit.SECONDS);
+		assertThat(connected).isTrue();
+
+		// Send message to establish session
+		var testMessage = createTestMessage();
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// Clean up
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	private McpSchema.JSONRPCRequest createTestMessage() {
+		var initializeRequest = new McpSchema.InitializeRequest(ProtocolVersions.MCP_2025_03_26,
+				McpSchema.ClientCapabilities.builder().roots(true).build(),
+				new McpSchema.Implementation("Test Client", "1.0.0"));
+		return new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE, "test-id",
+				initializeRequest);
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index 995cbd165..5d048353c 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -11,6 +11,7 @@
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -29,6 +30,7 @@
 import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
 import reactor.core.scheduler.Schedulers;
 
+@Timeout(15)
 class WebMvcSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
index 802363d59..c7c1e710d 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
@@ -11,6 +11,7 @@
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -29,6 +30,7 @@
 import io.modelcontextprotocol.server.transport.WebMvcStatelessServerTransport;
 import reactor.core.scheduler.Schedulers;
 
+@Timeout(15)
 class WebMvcStatelessIntegrationTests extends AbstractStatelessIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
index 800065915..16012e7d9 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -11,6 +11,7 @@
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -29,6 +30,7 @@
 import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
 import reactor.core.scheduler.Schedulers;
 
+@Timeout(15)
 class WebMvcStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TestUtil.findAvailablePort();
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 067fbac2c..ea3739da5 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -486,7 +486,8 @@ void testAddRoot() {
 	void testAddRootWithNullValue() {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
 			StepVerifier.create(mcpAsyncClient.addRoot(null))
-				.consumeErrorWith(e -> assertThat(e).isInstanceOf(McpError.class).hasMessage("Root must not be null"))
+				.consumeErrorWith(e -> assertThat(e).isInstanceOf(IllegalArgumentException.class)
+					.hasMessage("Root must not be null"))
 				.verify();
 		});
 	}
@@ -505,7 +506,7 @@ void testRemoveRoot() {
 	void testRemoveNonExistentRoot() {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
 			StepVerifier.create(mcpAsyncClient.removeRoot("nonexistent-uri"))
-				.consumeErrorWith(e -> assertThat(e).isInstanceOf(McpError.class)
+				.consumeErrorWith(e -> assertThat(e).isInstanceOf(IllegalStateException.class)
 					.hasMessage("Root with uri 'nonexistent-uri' not found"))
 				.verify();
 		});
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
index 2e0b51748..2cc1c5dba 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
@@ -289,9 +289,7 @@ public  Mono withIntitialization(String actionName, Function this.initializationRef.get())
 				.timeout(this.initializationTimeout)
 				.onErrorResume(ex -> {
-					logger.warn("Failed to initialize", ex);
-					return Mono.error(
-							new McpError("Client failed to initialize " + actionName + " due to: " + ex.getMessage()));
+					return Mono.error(new RuntimeException("Client failed to initialize " + actionName, ex));
 				})
 				.flatMap(operation);
 		});
@@ -316,8 +314,10 @@ private Mono doInitialize(DefaultInitialization init
 					initializeResult.instructions());
 
 			if (!this.protocolVersions.contains(initializeResult.protocolVersion())) {
-				return Mono.error(new McpError(
-						"Unsupported protocol version from the server: " + initializeResult.protocolVersion()));
+				return Mono.error(McpError.builder(-32602)
+					.message("Unsupported protocol version")
+					.data("Unsupported protocol version from the server: " + initializeResult.protocolVersion())
+					.build());
 			}
 
 			return mcpClientSession.sendNotification(McpSchema.METHOD_NOTIFICATION_INITIALIZED, null)
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 0f2ee19fa..228313beb 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -190,7 +190,8 @@ public class McpAsyncClient {
 		// Sampling Handler
 		if (this.clientCapabilities.sampling() != null) {
 			if (features.samplingHandler() == null) {
-				throw new McpError("Sampling handler must not be null when client capabilities include sampling");
+				throw new IllegalArgumentException(
+						"Sampling handler must not be null when client capabilities include sampling");
 			}
 			this.samplingHandler = features.samplingHandler();
 			requestHandlers.put(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE, samplingCreateMessageHandler());
@@ -199,7 +200,8 @@ public class McpAsyncClient {
 		// Elicitation Handler
 		if (this.clientCapabilities.elicitation() != null) {
 			if (features.elicitationHandler() == null) {
-				throw new McpError("Elicitation handler must not be null when client capabilities include elicitation");
+				throw new IllegalArgumentException(
+						"Elicitation handler must not be null when client capabilities include elicitation");
 			}
 			this.elicitationHandler = features.elicitationHandler();
 			requestHandlers.put(McpSchema.METHOD_ELICITATION_CREATE, elicitationCreateHandler());
@@ -413,15 +415,15 @@ public Mono ping() {
 	public Mono addRoot(Root root) {
 
 		if (root == null) {
-			return Mono.error(new McpError("Root must not be null"));
+			return Mono.error(new IllegalArgumentException("Root must not be null"));
 		}
 
 		if (this.clientCapabilities.roots() == null) {
-			return Mono.error(new McpError("Client must be configured with roots capabilities"));
+			return Mono.error(new IllegalStateException("Client must be configured with roots capabilities"));
 		}
 
 		if (this.roots.containsKey(root.uri())) {
-			return Mono.error(new McpError("Root with uri '" + root.uri() + "' already exists"));
+			return Mono.error(new IllegalStateException("Root with uri '" + root.uri() + "' already exists"));
 		}
 
 		this.roots.put(root.uri(), root);
@@ -447,11 +449,11 @@ public Mono addRoot(Root root) {
 	public Mono removeRoot(String rootUri) {
 
 		if (rootUri == null) {
-			return Mono.error(new McpError("Root uri must not be null"));
+			return Mono.error(new IllegalArgumentException("Root uri must not be null"));
 		}
 
 		if (this.clientCapabilities.roots() == null) {
-			return Mono.error(new McpError("Client must be configured with roots capabilities"));
+			return Mono.error(new IllegalStateException("Client must be configured with roots capabilities"));
 		}
 
 		Root removed = this.roots.remove(rootUri);
@@ -469,7 +471,7 @@ public Mono removeRoot(String rootUri) {
 			}
 			return Mono.empty();
 		}
-		return Mono.error(new McpError("Root with uri '" + rootUri + "' not found"));
+		return Mono.error(new IllegalStateException("Root with uri '" + rootUri + "' not found"));
 	}
 
 	/**
@@ -540,7 +542,7 @@ private RequestHandler elicitationCreateHandler() {
 	public Mono callTool(McpSchema.CallToolRequest callToolRequest) {
 		return this.initializer.withIntitialization("calling tools", init -> {
 			if (init.initializeResult().capabilities().tools() == null) {
-				return Mono.error(new McpError("Server does not provide tools capability"));
+				return Mono.error(new IllegalStateException("Server does not provide tools capability"));
 			}
 			return init.mcpSession()
 				.sendRequest(McpSchema.METHOD_TOOLS_CALL, callToolRequest, CALL_TOOL_RESULT_TYPE_REF);
@@ -569,7 +571,7 @@ public Mono listTools() {
 	public Mono listTools(String cursor) {
 		return this.initializer.withIntitialization("listing tools", init -> {
 			if (init.initializeResult().capabilities().tools() == null) {
-				return Mono.error(new McpError("Server does not provide tools capability"));
+				return Mono.error(new IllegalStateException("Server does not provide tools capability"));
 			}
 			return init.mcpSession()
 				.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
@@ -633,7 +635,7 @@ public Mono listResources() {
 	public Mono listResources(String cursor) {
 		return this.initializer.withIntitialization("listing resources", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
-				return Mono.error(new McpError("Server does not provide the resources capability"));
+				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
 			return init.mcpSession()
 				.sendRequest(McpSchema.METHOD_RESOURCES_LIST, new McpSchema.PaginatedRequest(cursor),
@@ -665,7 +667,7 @@ public Mono readResource(McpSchema.Resource resour
 	public Mono readResource(McpSchema.ReadResourceRequest readResourceRequest) {
 		return this.initializer.withIntitialization("reading resources", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
-				return Mono.error(new McpError("Server does not provide the resources capability"));
+				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
 			return init.mcpSession()
 				.sendRequest(McpSchema.METHOD_RESOURCES_READ, readResourceRequest, READ_RESOURCE_RESULT_TYPE_REF);
@@ -703,7 +705,7 @@ public Mono listResourceTemplates() {
 	public Mono listResourceTemplates(String cursor) {
 		return this.initializer.withIntitialization("listing resource templates", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
-				return Mono.error(new McpError("Server does not provide the resources capability"));
+				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
 			return init.mcpSession()
 				.sendRequest(McpSchema.METHOD_RESOURCES_TEMPLATES_LIST, new McpSchema.PaginatedRequest(cursor),
@@ -863,7 +865,7 @@ private NotificationHandler asyncLoggingNotificationHandler(
 	 */
 	public Mono setLoggingLevel(LoggingLevel loggingLevel) {
 		if (loggingLevel == null) {
-			return Mono.error(new McpError("Logging level must not be null"));
+			return Mono.error(new IllegalArgumentException("Logging level must not be null"));
 		}
 
 		return this.initializer.withIntitialization("setting logging level", init -> {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 473f71fbb..0f3511afb 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -24,10 +24,10 @@
 
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.spec.McpClientTransport;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
+import io.modelcontextprotocol.spec.McpTransportException;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
 import reactor.core.Disposable;
@@ -431,7 +431,7 @@ public Mono connect(Function, Mono> h
 									return Flux.empty(); // No further processing needed
 								}
 								else {
-									sink.error(new McpError("Failed to handle SSE endpoint event"));
+									sink.error(new RuntimeException("Failed to handle SSE endpoint event"));
 								}
 							}
 							else if (MESSAGE_EVENT_TYPE.equals(responseEvent.sseEvent().event())) {
@@ -446,8 +446,7 @@ else if (MESSAGE_EVENT_TYPE.equals(responseEvent.sseEvent().event())) {
 							}
 						}
 						catch (IOException e) {
-							logger.error("Error processing SSE event", e);
-							sink.error(new McpError("Error processing SSE event"));
+							sink.error(new McpTransportException("Error processing SSE event", e));
 						}
 					}
 					return Flux.error(
@@ -520,8 +519,7 @@ private Mono serializeMessage(final JSONRPCMessage message) {
 				return Mono.just(objectMapper.writeValueAsString(message));
 			}
 			catch (IOException e) {
-				// TODO: why McpError and not RuntimeException?
-				return Mono.error(new McpError("Failed to serialize message"));
+				return Mono.error(new McpTransportException("Failed to serialize message", e));
 			}
 		});
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index a9e5897b9..93c28422a 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -30,8 +30,8 @@
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportException;
 import io.modelcontextprotocol.spec.McpTransportSession;
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.spec.McpTransportStream;
@@ -288,9 +288,8 @@ private Mono reconnect(McpTransportStream stream) {
 
 										}
 										catch (IOException ioException) {
-											return Flux.error(
-													new McpError("Error parsing JSON-RPC message: "
-															+ responseEvent.sseEvent().data()));
+											return Flux.error(new McpTransportException(
+													"Error parsing JSON-RPC message: " + responseEvent, ioException));
 										}
 									}
 									else {
@@ -304,19 +303,39 @@ else if (statusCode == METHOD_NOT_ALLOWED) { // NotAllowed
 									return Flux.empty();
 								}
 								else if (statusCode == NOT_FOUND) {
-									String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
-									McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
-											"Session not found for session ID: " + sessionIdRepresentation);
-									return Flux.error(exception);
+
+									if (transportSession != null && transportSession.sessionId().isPresent()) {
+										// only if the request was sent with a session id
+										// and the response is 404, we consider it a
+										// session not found error.
+										logger.debug("Session not found for session ID: {}",
+												transportSession.sessionId().get());
+										String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
+										McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
+												"Session not found for session ID: " + sessionIdRepresentation);
+										return Flux.error(exception);
+									}
+									return Flux.error(
+											new McpTransportException("Server Not Found. Status code:" + statusCode
+													+ ", response-event:" + responseEvent));
 								}
 								else if (statusCode == BAD_REQUEST) {
-									String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
-									McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
-											"Session not found for session ID: " + sessionIdRepresentation);
-									return Flux.error(exception);
+									if (transportSession != null && transportSession.sessionId().isPresent()) {
+										// only if the request was sent with a session id
+										// and thre response is 404, we consider it a
+										// session not found error.
+										String sessionIdRepresentation = sessionIdOrPlaceholder(transportSession);
+										McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
+												"Session not found for session ID: " + sessionIdRepresentation);
+										return Flux.error(exception);
+									}
+									return Flux.error(
+											new McpTransportException("Bad Request. Status code:" + statusCode
+													+ ", response-event:" + responseEvent));
+
 								}
 
-								return Flux.error(new McpError(
+								return Flux.error(new McpTransportException(
 										"Received unrecognized SSE event type: " + responseEvent.sseEvent().event()));
 							}).flatMap(
@@ -468,8 +487,8 @@ else if (contentType.contains(TEXT_EVENT_STREAM)) {
 									return Flux.from(sessionStream.consumeSseStream(Flux.just(idWithMessages)));
 								}
 								catch (IOException ioException) {
-									return Flux.error(
-											new McpError("Error parsing JSON-RPC message: " + sseEvent.data()));
+									return Flux.error(new McpTransportException(
+											"Error parsing JSON-RPC message: " + responseEvent, ioException));
 								}
 							});
 					}
@@ -485,8 +504,8 @@ else if (contentType.contains(APPLICATION_JSON)) {
 							return Mono.just(McpSchema.deserializeJsonRpcMessage(objectMapper, data));
 						}
 						catch (IOException e) {
-							// TODO: this should be a McpTransportError
-							return Mono.error(e);
+							return Mono.error(new McpTransportException(
+									"Error deserializing JSON-RPC message: " + responseEvent, e));
 						}
 					}
 					logger.warn("Unknown media type {} returned for POST in session {}", contentType,
@@ -496,18 +515,32 @@ else if (contentType.contains(APPLICATION_JSON)) {
 							new RuntimeException("Unknown media type returned: " + contentType));
 				}
 				else if (statusCode == NOT_FOUND) {
-					McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
-							"Session not found for session ID: " + sessionRepresentation);
-					return Flux.error(exception);
+					if (transportSession != null && transportSession.sessionId().isPresent()) {
+						// only if the request was sent with a session id and the
+						// response is 404, we consider it a session not found error.
+						logger.debug("Session not found for session ID: {}", transportSession.sessionId().get());
+						McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
+								"Session not found for session ID: " + sessionRepresentation);
+						return Flux.error(exception);
+					}
+					return Flux.error(new McpTransportException(
+							"Server Not Found. Status code:" + statusCode + ", response-event:" + responseEvent));
 				}
-				// Some implementations can return 400 when presented with a
-				// session id that it doesn't know about, so we will
-				// invalidate the session
-				// https://github.com/modelcontextprotocol/typescript-sdk/issues/389
 				else if (statusCode == BAD_REQUEST) {
-					McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
-							"Session not found for session ID: " + sessionRepresentation);
-					return Flux.error(exception);
+					// Some implementations can return 400 when presented with a
+					// session id that it doesn't know about, so we will
+					// invalidate the session
+					// https://github.com/modelcontextprotocol/typescript-sdk/issues/389
+
+					if (transportSession != null && transportSession.sessionId().isPresent()) {
+						// only if the request was sent with a session id and the
+						// response is 404, we consider it a session not found error.
+						McpTransportSessionNotFoundException exception = new McpTransportSessionNotFoundException(
+								"Session not found for session ID: " + sessionRepresentation);
+						return Flux.error(exception);
+					}
+					return Flux.error(new McpTransportException(
+							"Bad Request. Status code:" + statusCode + ", response-event:" + responseEvent));
 				}
 
 				return Flux.error(
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
index 4d9bdea5d..296d1a17d 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
@@ -15,7 +15,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpTransportException;
 import reactor.core.publisher.BaseSubscriber;
 import reactor.core.publisher.FluxSink;
 
@@ -178,8 +178,7 @@ else if (line.startsWith(":")) {
 				}
 				else {
 					// If the response is not successful, emit an error
-					// TODO: This should be a McpTransportError
-					this.sink.error(new McpError(
+					this.sink.error(new McpTransportException(
 							"Invalid SSE response. Status code: " + this.responseInfo.statusCode() + " Line: " + line));
 
 				}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java
new file mode 100644
index 000000000..cfd3dae31
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java
@@ -0,0 +1,38 @@
+/*
+* Copyright 2025 - 2025 the original author or authors.
+*/
+package io.modelcontextprotocol.spec;
+
+/**
+ * Exception thrown when there is an issue with the transport layer of the Model Context
+ * Protocol (MCP).
+ *
+ * 

+ * This exception is used to indicate errors that occur during communication between the
+ * MCP client and server, such as connection failures, protocol violations, or unexpected
+ * responses.
+ *
+ * @author Christian Tzolov
+ */
+public class McpTransportException extends RuntimeException {
+
+	private static final long serialVersionUID = 1L;
+
+	public McpTransportException(String message) {
+		super(message);
+	}
+
+	public McpTransportException(String message, Throwable cause) {
+		super(message, cause);
+	}
+
+	public McpTransportException(Throwable cause) {
+		super(cause);
+	}
+
+	public McpTransportException(String message, Throwable cause, boolean enableSuppression,
+			boolean writableStackTrace) {
+		super(message, cause, enableSuppression, writableStackTrace);
+	}
+
+}
\ No newline at end of file
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index e912e1dd6..3626d8ca0 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -487,7 +487,8 @@ void testAddRoot() {
 	void testAddRootWithNullValue() {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
 			StepVerifier.create(mcpAsyncClient.addRoot(null))
-				.consumeErrorWith(e -> assertThat(e).isInstanceOf(McpError.class).hasMessage("Root must not be null"))
+				.consumeErrorWith(e -> assertThat(e).isInstanceOf(IllegalArgumentException.class)
+					.hasMessage("Root must not be null"))
 				.verify();
 		});
 	}
@@ -506,7 +507,7 @@ void testRemoveRoot() {
 	void testRemoveNonExistentRoot() {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
 			StepVerifier.create(mcpAsyncClient.removeRoot("nonexistent-uri"))
-				.consumeErrorWith(e -> assertThat(e).isInstanceOf(McpError.class)
+				.consumeErrorWith(e -> assertThat(e).isInstanceOf(IllegalStateException.class)
 					.hasMessage("Root with uri 'nonexistent-uri' not found"))
 				.verify();
 		});
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
index c8d691924..02021edbf 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
@@ -16,7 +16,6 @@
 import org.mockito.MockitoAnnotations;
 
 import io.modelcontextprotocol.spec.McpClientSession;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import reactor.core.publisher.Mono;
@@ -154,7 +153,7 @@ void shouldFailForUnsupportedProtocolVersion() {
 			.thenReturn(Mono.just(unsupportedResult));
 
 		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
-			.expectError(McpError.class)
+			.expectError(RuntimeException.class)
 			.verify();
 
 		verify(mockClientSession, never()).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any());
@@ -178,7 +177,7 @@ void shouldTimeoutOnSlowInitialization() {
 					init -> Mono.just(init.initializeResult())), () -> virtualTimeScheduler, Long.MAX_VALUE)
 			.expectSubscription()
 			.expectNoEvent(INITIALIZE_TIMEOUT)
-			.expectError(McpError.class)
+			.expectError(RuntimeException.class)
 			.verify();
 	}
 
@@ -234,7 +233,7 @@ void shouldHandleInitializationFailure() {
 			.thenReturn(Mono.error(new RuntimeException("Connection failed")));
 
 		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
-			.expectError(McpError.class)
+			.expectError(RuntimeException.class)
 			.verify();
 
 		assertThat(initializer.isInitialized()).isFalse();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
index b2fd7fb65..daa6b5e1e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
@@ -13,7 +13,6 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.MockMcpClientTransport;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
@@ -373,7 +372,7 @@ void testSamplingCreateMessageRequestHandlingWithNullHandler() {
 		// Create client with sampling capability but null handler
 		assertThatThrownBy(
 				() -> McpClient.async(transport).capabilities(ClientCapabilities.builder().sampling().build()).build())
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Sampling handler must not be null when client capabilities include sampling");
 	}
 
@@ -521,7 +520,7 @@ void testElicitationCreateRequestHandlingWithNullHandler() {
 		// Create client with elicitation capability but null handler
 		assertThatThrownBy(() -> McpClient.async(transport)
 			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.build()).isInstanceOf(McpError.class)
+			.build()).isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Elicitation handler must not be null when client capabilities include elicitation");
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
index 36216988f..3feb1d05c 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
@@ -113,7 +113,7 @@ void shouldFailForUnsupportedVersion() {
 						new McpSchema.InitializeResult(unsupportedVersion, null,
 								new McpSchema.Implementation("test-server", "1.0.0"), null),
 						null));
-			}).expectError(McpError.class).verify();
+			}).expectError(RuntimeException.class).verify();
 		}
 		finally {
 			StepVerifier.create(client.closeGracefully()).verifyComplete();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
new file mode 100644
index 000000000..2b502a83b
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
@@ -0,0 +1,345 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+
+import com.sun.net.httpserver.HttpServer;
+
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.HttpHeaders;
+import io.modelcontextprotocol.spec.McpClientTransport;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportException;
+import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
+import io.modelcontextprotocol.spec.ProtocolVersions;
+import reactor.test.StepVerifier;
+
+/**
+ * Tests for error handling changes in HttpClientStreamableHttpTransport. Specifically
+ * tests the distinction between session-related errors and general transport errors for
+ * 404 and 400 status codes.
+ *
+ * @author Christian Tzolov
+ */
+@Timeout(15)
+public class HttpClientStreamableHttpTransportErrorHandlingTest {
+
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
+	private static final String HOST = "http://localhost:" + PORT;
+
+	private HttpServer server;
+
+	private AtomicReference serverResponseStatus = new AtomicReference<>(200);
+
+	private AtomicReference currentServerSessionId = new AtomicReference<>(null);
+
+	private AtomicReference lastReceivedSessionId = new AtomicReference<>(null);
+
+	private McpClientTransport transport;
+
+	@BeforeEach
+	void startServer() throws IOException {
+		server = HttpServer.create(new InetSocketAddress(PORT), 0);
+
+		// Configure the /mcp endpoint with dynamic response
+		server.createContext("/mcp", httpExchange -> {
+			if ("DELETE".equals(httpExchange.getRequestMethod())) {
+				httpExchange.sendResponseHeaders(200, 0);
+			}
+			else {
+				// Capture session ID from request if present
+				String requestSessionId = httpExchange.getRequestHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+				lastReceivedSessionId.set(requestSessionId);
+
+				int status = serverResponseStatus.get();
+
+				// Set response headers
+				httpExchange.getResponseHeaders().set("Content-Type", "application/json");
+
+				// Add session ID to response if configured
+				String responseSessionId = currentServerSessionId.get();
+				if (responseSessionId != null) {
+					httpExchange.getResponseHeaders().set(HttpHeaders.MCP_SESSION_ID, responseSessionId);
+				}
+
+				// Send response based on configured status
+				if (status == 200) {
+					String response = "{\"jsonrpc\":\"2.0\",\"result\":{},\"id\":\"test-id\"}";
+					httpExchange.sendResponseHeaders(200, response.length());
+					httpExchange.getResponseBody().write(response.getBytes());
+				}
+				else {
+					httpExchange.sendResponseHeaders(status, 0);
+				}
+			}
+			httpExchange.close();
+		});
+
+		server.setExecutor(null);
+		server.start();
+
+		transport = HttpClientStreamableHttpTransport.builder(HOST).build();
+	}
+
+	@AfterEach
+	void stopServer() {
+		if (server != null) {
+			server.stop(0);
+		}
+	}
+
+	/**
+	 * Test that 404 response WITHOUT session ID throws McpTransportException (not
+	 * SessionNotFoundException)
+	 */
+	@Test
+	void test404WithoutSessionId() {
+		serverResponseStatus.set(404);
+		currentServerSessionId.set(null); // No session ID in response
+
+		var testMessage = createTestRequestMessage();
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMatches(throwable -> throwable instanceof McpTransportException
+					&& throwable.getMessage().contains("Not Found") && throwable.getMessage().contains("404")
+					&& !(throwable instanceof McpTransportSessionNotFoundException))
+			.verify();
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	/**
+	 * Test that 404 response WITH session ID throws McpTransportSessionNotFoundException
+	 */
+	@Test
+	void test404WithSessionId() {
+		// First establish a session
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("test-session-123");
+
+		// Set up exception handler to verify session invalidation
+		@SuppressWarnings("unchecked")
+		Consumer exceptionHandler = mock(Consumer.class);
+		transport.setExceptionHandler(exceptionHandler);
+
+		// Connect with handler
+		StepVerifier.create(transport.connect(msg -> msg)).verifyComplete();
+
+		// Send initial message to establish session
+		var testMessage = createTestRequestMessage();
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// The session should now be established, next request will include session ID
+		// Now return 404 for next request
+		serverResponseStatus.set(404);
+
+		// Send another message - should get SessionNotFoundException
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectError(McpTransportSessionNotFoundException.class)
+			.verify();
+
+		// Verify exception handler was called with SessionNotFoundException
+		verify(exceptionHandler).accept(any(McpTransportSessionNotFoundException.class));
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	/**
+	 * Test that 400 response WITHOUT session ID throws McpTransportException (not
+	 * SessionNotFoundException)
+	 */
+	@Test
+	void test400WithoutSessionId() {
+		serverResponseStatus.set(400);
+		currentServerSessionId.set(null); // No session ID
+
+		var testMessage = createTestRequestMessage();
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMatches(throwable -> throwable instanceof McpTransportException
+					&& throwable.getMessage().contains("Bad Request") && throwable.getMessage().contains("400")
+					&& !(throwable instanceof McpTransportSessionNotFoundException))
+			.verify();
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	/**
+	 * Test that 400 response WITH session ID throws McpTransportSessionNotFoundException
+	 * This handles the case mentioned in the code comment about some implementations
+	 * returning 400 for unknown session IDs.
+	 */
+	@Test
+	void test400WithSessionId() {
+		// First establish a session
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("test-session-456");
+
+		// Set up exception handler
+		@SuppressWarnings("unchecked")
+		Consumer exceptionHandler = mock(Consumer.class);
+		transport.setExceptionHandler(exceptionHandler);
+
+		// Connect with handler
+		StepVerifier.create(transport.connect(msg -> msg)).verifyComplete();
+
+		// Send initial message to establish session
+		var testMessage = createTestRequestMessage();
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// The session should now be established, next request will include session ID
+		// Now return 400 for next request (simulating unknown session ID)
+		serverResponseStatus.set(400);
+
+		// Send another message - should get SessionNotFoundException
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectError(McpTransportSessionNotFoundException.class)
+			.verify();
+
+		// Verify exception handler was called
+		verify(exceptionHandler).accept(any(McpTransportSessionNotFoundException.class));
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	/**
+	 * Test session recovery after SessionNotFoundException Verifies that a new session
+	 * can be established after the old one is invalidated
+	 */
+	@Test
+	void testSessionRecoveryAfter404() {
+		// First establish a session
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("session-1");
+
+		// Send initial message to establish session
+		var testMessage = createTestRequestMessage();
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		assertThat(lastReceivedSessionId.get()).isNull();
+
+		// The session should now be established
+		// Simulate session loss - return 404
+		serverResponseStatus.set(404);
+
+		// This should fail with SessionNotFoundException
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectError(McpTransportSessionNotFoundException.class)
+			.verify();
+
+		// Now server is back with new session
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("session-2");
+		lastReceivedSessionId.set(null); // Reset to verify new session
+
+		// Should be able to establish new session
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// Verify no session ID was sent (since old session was invalidated)
+		assertThat(lastReceivedSessionId.get()).isNull();
+
+		// Next request should use the new session ID
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// Session ID should now be sent with requests
+		assertThat(lastReceivedSessionId.get()).isEqualTo("session-2");
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	/**
+	 * Test that reconnect (GET request) also properly handles 404/400 errors
+	 */
+	@Test
+	void testReconnectErrorHandling() {
+
+		// Set up SSE endpoint for GET requests
+		server.createContext("/mcp-sse", exchange -> {
+			String method = exchange.getRequestMethod();
+			String requestSessionId = exchange.getRequestHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
+
+			if ("GET".equals(method)) {
+				int status = serverResponseStatus.get();
+
+				if (status == 404 && requestSessionId != null) {
+					// 404 with session ID - should trigger SessionNotFoundException
+					exchange.sendResponseHeaders(404, 0);
+				}
+				else if (status == 404) {
+					// 404 without session ID - should trigger McpTransportException
+					exchange.sendResponseHeaders(404, 0);
+				}
+				else {
+					// Normal SSE response
+					exchange.getResponseHeaders().set("Content-Type", "text/event-stream");
+					exchange.sendResponseHeaders(200, 0);
+					// Send a test SSE event
+					String sseData = "event: message\ndata: {\"jsonrpc\":\"2.0\",\"method\":\"test\",\"params\":{}}\n\n";
+					exchange.getResponseBody().write(sseData.getBytes());
+				}
+			}
+			else {
+				// POST request handling
+				exchange.getResponseHeaders().set("Content-Type", "application/json");
+				String responseSessionId = currentServerSessionId.get();
+				if (responseSessionId != null) {
+					exchange.getResponseHeaders().set(HttpHeaders.MCP_SESSION_ID, responseSessionId);
+				}
+				String response = "{\"jsonrpc\":\"2.0\",\"result\":{},\"id\":\"test-id\"}";
+				exchange.sendResponseHeaders(200, response.length());
+				exchange.getResponseBody().write(response.getBytes());
+			}
+			exchange.close();
+		});
+
+		// Test with session ID - should get SessionNotFoundException
+		serverResponseStatus.set(200);
+		currentServerSessionId.set("sse-session-1");
+
+		var transport = HttpClientStreamableHttpTransport.builder(HOST)
+			.endpoint("/mcp-sse")
+			.openConnectionOnStartup(true) // This will trigger GET request on connect
+			.build();
+
+		// First connect successfully
+		StepVerifier.create(transport.connect(msg -> msg)).verifyComplete();
+
+		// Send message to establish session
+		var testMessage = createTestRequestMessage();
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+
+		// Now simulate server returning 404 on reconnect
+		serverResponseStatus.set(404);
+
+		// This should trigger reconnect which will fail
+		// The error should be handled internally and passed to exception handler
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+	}
+
+	private McpSchema.JSONRPCRequest createTestRequestMessage() {
+		var initializeRequest = new McpSchema.InitializeRequest(ProtocolVersions.MCP_2025_03_26,
+				McpSchema.ClientCapabilities.builder().roots(true).build(),
+				new McpSchema.Implementation("Test Client", "1.0.0"));
+		return new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE, "test-id",
+				initializeRequest);
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
index 56e74218f..823c28d8e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
@@ -13,6 +13,7 @@
 import org.apache.catalina.startup.Tomcat;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
@@ -23,6 +24,7 @@
 import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 
+@Timeout(15)
 class HttpServletSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TomcatTestUtil.findAvailablePort();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index 4c3f22d76..a8951e6dc 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -29,6 +29,7 @@
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
 import org.springframework.mock.web.MockHttpServletRequest;
@@ -49,6 +50,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Timeout(15)
 class HttpServletStatelessIntegrationTests {
 
 	private static final int PORT = TomcatTestUtil.findAvailablePort();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 6ac10014e..8a8675d95 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -13,6 +13,7 @@
 import org.apache.catalina.startup.Tomcat;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
@@ -23,6 +24,7 @@
 import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 
+@Timeout(15)
 class HttpServletStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
 
 	private static final int PORT = TomcatTestUtil.findAvailablePort();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
index e329188f9..f915895be 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
@@ -27,10 +27,12 @@
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
 import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
+import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
 import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
 import io.modelcontextprotocol.spec.McpSchema.Prompt;
 import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
 import io.modelcontextprotocol.spec.McpSchema.ReadResourceResult;
+import io.modelcontextprotocol.spec.McpSchema.Resource;
 import io.modelcontextprotocol.spec.McpSchema.ResourceReference;
 import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
@@ -84,7 +86,7 @@ public void after() {
 				tomcat.destroy();
 			}
 			catch (LifecycleException e) {
-				throw new RuntimeException("Failed to stop Tomcat", e);
+				e.printStackTrace();
 			}
 		}
 	}
@@ -99,8 +101,13 @@ void testCompletionHandlerReceivesContext() {
 
 		ResourceReference resourceRef = new ResourceReference("ref/resource", "test://resource/{param}");
 
-		McpSchema.Resource resource = new McpSchema.Resource("test://resource/{param}", "Test Resource",
-				"A resource for testing", "text/plain", 123L, null);
+		var resource = Resource.builder()
+			.uri("test://resource/{param}")
+			.name("Test Resource")
+			.description("A resource for testing")
+			.mimeType("text/plain")
+			.size(123L)
+			.build();
 
 		var mcpServer = McpServer.sync(mcpServerTransportProvider)
 			.capabilities(ServerCapabilities.builder().completions().build())
@@ -199,8 +206,13 @@ else if ("products_db".equals(db)) {
 			return new CompleteResult(new CompleteResult.CompleteCompletion(List.of(), 0, false));
 		};
 
-		McpSchema.Resource resource = new McpSchema.Resource("db://{database}/{table}", "Database Table",
-				"Resource representing a table in a database", "application/json", 456L, null);
+		McpSchema.Resource resource = Resource.builder()
+			.uri("db://{database}/{table}")
+			.name("Database Table")
+			.description("Resource representing a table in a database")
+			.mimeType("application/json")
+			.size(456L)
+			.build();
 
 		var mcpServer = McpServer.sync(mcpServerTransportProvider)
 			.capabilities(ServerCapabilities.builder().completions().build())
@@ -254,7 +266,10 @@ void testCompletionErrorOnMissingContext() {
 						// Check if database context is provided
 						if (request.context() == null || request.context().arguments() == null
 								|| !request.context().arguments().containsKey("database")) {
-							throw new McpError("Please select a database first to see available tables");
+
+							throw McpError.builder(ErrorCodes.INVALID_REQUEST)
+								.message("Please select a database first to see available tables")
+								.build();
 						}
 						// Normal completion if context is provided
 						String db = request.context().arguments().get("database");
@@ -268,8 +283,13 @@ void testCompletionErrorOnMissingContext() {
 			return new CompleteResult(new CompleteResult.CompleteCompletion(List.of(), 0, false));
 		};
 
-		McpSchema.Resource resource = new McpSchema.Resource("db://{database}/{table}", "Database Table",
-				"Resource representing a table in a database", "application/json", 456L, null);
+		McpSchema.Resource resource = Resource.builder()
+			.uri("db://{database}/{table}")
+			.name("Database Table")
+			.description("Resource representing a table in a database")
+			.mimeType("application/json")
+			.size(456L)
+			.build();
 
 		var mcpServer = McpServer.sync(mcpServerTransportProvider)
 			.capabilities(ServerCapabilities.builder().completions().build())

From 713ee1add0e29d184224aabdf06d024ef30a2754 Mon Sep 17 00:00:00 2001
From: Jordan Zimmerman 
Date: Wed, 6 Aug 2025 22:40:21 +0100
Subject: [PATCH 049/125] fix: ServerCapabilities should not enable logging by
 default (#463)

- Change LoggingCapabilities from default-initialized to nullable in ServerCapabilities
- Add check if server logging is enabled in McpAsyncClient before setting logging level
- Ensure McpAsyncServer always enables logging capabilities when built
- Ensure McpStatelessAsyncServer has disabled logging capability by default
- Update tests to verify logging capabilities can be null

Signed-off-by: Christian Tzolov 
Co-authored-by: Christian Tzolov 
---
 .../AbstractMcpClientServerIntegrationTests.java              | 4 ++--
 .../java/io/modelcontextprotocol/client/McpAsyncClient.java   | 3 +++
 .../java/io/modelcontextprotocol/server/McpAsyncServer.java   | 4 ++--
 mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java | 2 +-
 .../client/McpAsyncClientResponseHandlerTests.java            | 1 +
 5 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 26fd71d2b..8e041d91e 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -950,7 +950,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 		List receivedNotifications = new CopyOnWriteArrayList<>();
 
 		var clientBuilder = clientBuilders.get(clientType);
-		;
+
 		// Create server with a tool that sends logging notifications
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder()
@@ -999,7 +999,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 			.build();
 
 		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
+			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(tool)
 			.build();
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 228313beb..eb6d42f68 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -869,6 +869,9 @@ public Mono setLoggingLevel(LoggingLevel loggingLevel) {
 		}
 
 		return this.initializer.withIntitialization("setting logging level", init -> {
+			if (init.initializeResult().capabilities().logging() == null) {
+				return Mono.error(new IllegalStateException("Server's Logging capabilities are not enabled!"));
+			}
 			var params = new McpSchema.SetLevelRequest(loggingLevel);
 			return init.mcpSession().sendRequest(McpSchema.METHOD_LOGGING_SET_LEVEL, params, OBJECT_TYPE_REF).then();
 		});
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index 5b5e838f3..a51c2e36c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -132,7 +132,7 @@ public class McpAsyncServer {
 		this.mcpTransportProvider = mcpTransportProvider;
 		this.objectMapper = objectMapper;
 		this.serverInfo = features.serverInfo();
-		this.serverCapabilities = features.serverCapabilities();
+		this.serverCapabilities = features.serverCapabilities().mutate().logging().build();
 		this.instructions = features.instructions();
 		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
 		this.resources.putAll(features.resources());
@@ -157,7 +157,7 @@ public class McpAsyncServer {
 		this.mcpTransportProvider = mcpTransportProvider;
 		this.objectMapper = objectMapper;
 		this.serverInfo = features.serverInfo();
-		this.serverCapabilities = features.serverCapabilities();
+		this.serverCapabilities = features.serverCapabilities().mutate().logging().build();
 		this.instructions = features.instructions();
 		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
 		this.resources.putAll(features.resources());
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index bd8a01555..8a109a8d1 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -548,7 +548,7 @@ public static class Builder {
 
 			private Map experimental;
 
-			private LoggingCapabilities logging = new LoggingCapabilities();
+			private LoggingCapabilities logging;
 
 			private PromptCapabilities prompts;
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
index daa6b5e1e..cab847512 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
@@ -80,6 +80,7 @@ void testSuccessfulInitialization() {
 		assertThat(result).isNotNull();
 		assertThat(result.protocolVersion()).isEqualTo(transport.protocolVersions().get(0));
 		assertThat(result.capabilities()).isEqualTo(serverCapabilities);
+		assertThat(result.capabilities().logging()).isNull();
 		assertThat(result.serverInfo()).isEqualTo(serverInfo);
 		assertThat(result.instructions()).isEqualTo("Test instructions");
 

From 888e55502699075a91cef492a96752f2f04624ab Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Mon, 25 Aug 2025 12:46:59 +0200
Subject: [PATCH 050/125] feat: implement identifier-based equals/hashCode for
 PromptReference (#514)

Ensure PromptReference equality is based solely on identifier and type fields, ignoring other fields like title

Signed-off-by: Christian Tzolov 
---
 .../modelcontextprotocol/spec/McpSchema.java  | 16 ++++
 .../spec/PromptReferenceEqualsTest.java       | 87 +++++++++++++++++++
 2 files changed, 103 insertions(+)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 8a109a8d1..3f8150271 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -2351,6 +2351,22 @@ public PromptReference(String name) {
 		public String identifier() {
 			return name();
 		}
+
+		@Override
+		public boolean equals(Object obj) {
+			if (this == obj)
+				return true;
+			if (obj == null || getClass() != obj.getClass())
+				return false;
+			PromptReference that = (PromptReference) obj;
+			return java.util.Objects.equals(identifier(), that.identifier())
+					&& java.util.Objects.equals(type(), that.type());
+		}
+
+		@Override
+		public int hashCode() {
+			return java.util.Objects.hash(identifier(), type());
+		}
 	}
 
 	/**
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java b/mcp/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
new file mode 100644
index 000000000..25e22f968
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
@@ -0,0 +1,87 @@
+/*
+* Copyright 2025 - 2025 the original author or authors.
+*/
+
+package io.modelcontextprotocol.spec;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Test class to verify the equals method implementation for PromptReference.
+ */
+class PromptReferenceEqualsTest {
+
+	@Test
+	void testEqualsWithSameIdentifierAndType() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Different Title");
+
+		assertTrue(ref1.equals(ref2), "PromptReferences with same identifier and type should be equal");
+		assertEquals(ref1.hashCode(), ref2.hashCode(), "Equal objects should have same hash code");
+	}
+
+	@Test
+	void testEqualsWithDifferentIdentifier() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt-1", "Test Title");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt-2", "Test Title");
+
+		assertFalse(ref1.equals(ref2), "PromptReferences with different identifiers should not be equal");
+	}
+
+	@Test
+	void testEqualsWithDifferentType() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/other", "test-prompt", "Test Title");
+
+		assertFalse(ref1.equals(ref2), "PromptReferences with different types should not be equal");
+	}
+
+	@Test
+	void testEqualsWithNull() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+
+		assertFalse(ref1.equals(null), "PromptReference should not be equal to null");
+	}
+
+	@Test
+	void testEqualsWithDifferentClass() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		String other = "not a PromptReference";
+
+		assertFalse(ref1.equals(other), "PromptReference should not be equal to different class");
+	}
+
+	@Test
+	void testEqualsWithSameInstance() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+
+		assertTrue(ref1.equals(ref1), "PromptReference should be equal to itself");
+	}
+
+	@Test
+	void testEqualsIgnoresTitle() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Title 1");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Title 2");
+		McpSchema.PromptReference ref3 = new McpSchema.PromptReference("ref/prompt", "test-prompt", null);
+
+		assertTrue(ref1.equals(ref2), "PromptReferences should be equal regardless of title");
+		assertTrue(ref1.equals(ref3), "PromptReferences should be equal even when one has null title");
+		assertTrue(ref2.equals(ref3), "PromptReferences should be equal even when one has null title");
+	}
+
+	@Test
+	void testHashCodeConsistency() {
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Different Title");
+
+		assertEquals(ref1.hashCode(), ref2.hashCode(), "Objects that are equal should have the same hash code");
+
+		// Call hashCode multiple times to ensure consistency
+		int hashCode1 = ref1.hashCode();
+		int hashCode2 = ref1.hashCode();
+		assertEquals(hashCode1, hashCode2, "Hash code should be consistent across multiple calls");
+	}
+
+}

From 94c03505c1ca1d606f4202d419fa61fbc13aee47 Mon Sep 17 00:00:00 2001
From: "He-Pin(kerr)" 
Date: Mon, 25 Aug 2025 21:46:17 +0800
Subject: [PATCH 051/125] fix: Fix SseLineSubscriber lacking request. (#507)

Signed-off-by: He-Pin 
---
 .../client/transport/ResponseSubscribers.java                | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
index 296d1a17d..945aeef78 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
@@ -141,7 +141,6 @@ protected void hookOnSubscribe(Subscription subscription) {
 
 		@Override
 		protected void hookOnNext(String line) {
-
 			if (line.isEmpty()) {
 				// Empty line means end of event
 				if (this.eventBuilder.length() > 0) {
@@ -158,23 +157,27 @@ protected void hookOnNext(String line) {
 					if (matcher.find()) {
 						this.eventBuilder.append(matcher.group(1).trim()).append("\n");
 					}
+					upstream().request(1);
 				}
 				else if (line.startsWith("id:")) {
 					var matcher = EVENT_ID_PATTERN.matcher(line);
 					if (matcher.find()) {
 						this.currentEventId.set(matcher.group(1).trim());
 					}
+					upstream().request(1);
 				}
 				else if (line.startsWith("event:")) {
 					var matcher = EVENT_TYPE_PATTERN.matcher(line);
 					if (matcher.find()) {
 						this.currentEventType.set(matcher.group(1).trim());
 					}
+					upstream().request(1);
 				}
 				else if (line.startsWith(":")) {
 					// Ignore comment lines starting with ":"
 					// This is a no-op, just to skip comments
 					logger.debug("Ignoring comment line: {}", line);
+					upstream().request(1);
 				}
 				else {
 					// If the response is not successful, emit an error

From cc67d8fa761d9122e03cc3c06d427739a6c0c633 Mon Sep 17 00:00:00 2001
From: Zizo <76683249+Zizo-Vi@users.noreply.github.com>
Date: Mon, 25 Aug 2025 22:14:28 +0800
Subject: [PATCH 052/125] fix: http streamable client connect timeout (#511)

* add http streamable client connect timeout
* add http sse client connect timeout

Co-authored-by: gongwn1 
---
 .../HttpClientSseClientTransport.java         | 25 +++++++++++++------
 .../HttpClientStreamableHttpTransport.java    | 23 +++++++++++++----
 2 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 0f3511afb..d87a27361 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -170,8 +170,7 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, String bas
 	@Deprecated(forRemoval = true)
 	public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpRequest.Builder requestBuilder,
 			String baseUri, String sseEndpoint, ObjectMapper objectMapper) {
-		this(clientBuilder.connectTimeout(Duration.ofSeconds(10)).build(), requestBuilder, baseUri, sseEndpoint,
-				objectMapper);
+		this(clientBuilder.build(), requestBuilder, baseUri, sseEndpoint, objectMapper);
 	}
 
 	/**
@@ -241,9 +240,7 @@ public static class Builder {
 
 		private String sseEndpoint = DEFAULT_SSE_ENDPOINT;
 
-		private HttpClient.Builder clientBuilder = HttpClient.newBuilder()
-			.version(HttpClient.Version.HTTP_1_1)
-			.connectTimeout(Duration.ofSeconds(10));
+		private HttpClient.Builder clientBuilder = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1);
 
 		private ObjectMapper objectMapper = new ObjectMapper();
 
@@ -252,6 +249,8 @@ public static class Builder {
 
 		private AsyncHttpRequestCustomizer httpRequestCustomizer = AsyncHttpRequestCustomizer.NOOP;
 
+		private Duration connectTimeout = Duration.ofSeconds(10);
+
 		/**
 		 * Creates a new builder instance.
 		 */
@@ -383,13 +382,25 @@ public Builder asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer asyncHttpRe
 			return this;
 		}
 
+		/**
+		 * Sets the connection timeout for the HTTP client.
+		 * @param connectTimeout the connection timeout duration
+		 * @return this builder
+		 */
+		public Builder connectTimeout(Duration connectTimeout) {
+			Assert.notNull(connectTimeout, "connectTimeout must not be null");
+			this.connectTimeout = connectTimeout;
+			return this;
+		}
+
 		/**
 		 * Builds a new {@link HttpClientSseClientTransport} instance.
 		 * @return a new transport instance
 		 */
 		public HttpClientSseClientTransport build() {
-			return new HttpClientSseClientTransport(clientBuilder.build(), requestBuilder, baseUri, sseEndpoint,
-					objectMapper, httpRequestCustomizer);
+			HttpClient httpClient = this.clientBuilder.connectTimeout(this.connectTimeout).build();
+			return new HttpClientSseClientTransport(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper,
+					httpRequestCustomizer);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index 93c28422a..d8c49ae2f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -588,9 +588,7 @@ public static class Builder {
 
 		private ObjectMapper objectMapper;
 
-		private HttpClient.Builder clientBuilder = HttpClient.newBuilder()
-			.version(HttpClient.Version.HTTP_1_1)
-			.connectTimeout(Duration.ofSeconds(10));
+		private HttpClient.Builder clientBuilder = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1);
 
 		private String endpoint = DEFAULT_ENDPOINT;
 
@@ -602,6 +600,8 @@ public static class Builder {
 
 		private AsyncHttpRequestCustomizer httpRequestCustomizer = AsyncHttpRequestCustomizer.NOOP;
 
+		private Duration connectTimeout = Duration.ofSeconds(10);
+
 		/**
 		 * Creates a new builder with the specified base URI.
 		 * @param baseUri the base URI of the MCP server
@@ -738,6 +738,17 @@ public Builder asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer asyncHttpRe
 			return this;
 		}
 
+		/**
+		 * Sets the connection timeout for the HTTP client.
+		 * @param connectTimeout the connection timeout duration
+		 * @return this builder
+		 */
+		public Builder connectTimeout(Duration connectTimeout) {
+			Assert.notNull(connectTimeout, "connectTimeout must not be null");
+			this.connectTimeout = connectTimeout;
+			return this;
+		}
+
 		/**
 		 * Construct a fresh instance of {@link HttpClientStreamableHttpTransport} using
 		 * the current builder configuration.
@@ -746,8 +757,10 @@ public Builder asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer asyncHttpRe
 		public HttpClientStreamableHttpTransport build() {
 			ObjectMapper objectMapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 
-			return new HttpClientStreamableHttpTransport(objectMapper, clientBuilder.build(), requestBuilder, baseUri,
-					endpoint, resumableStreams, openConnectionOnStartup, httpRequestCustomizer);
+			HttpClient httpClient = this.clientBuilder.connectTimeout(this.connectTimeout).build();
+
+			return new HttpClientStreamableHttpTransport(objectMapper, httpClient, requestBuilder, baseUri, endpoint,
+					resumableStreams, openConnectionOnStartup, httpRequestCustomizer);
 		}
 
 	}

From 6ec443c89a7d3d122a4ff74ddbb67bb7b53c477e Mon Sep 17 00:00:00 2001
From: "shaoyin.zj" 
Date: Tue, 26 Aug 2025 13:51:07 +0800
Subject: [PATCH 053/125] fix: When call the MCP SSE endpoint, the Content-Type
 header not passed by default (#489)

---
 .../client/transport/HttpClientSseClientTransport.java        | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index d87a27361..a92f26c4e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -244,8 +244,7 @@ public static class Builder {
 
 		private ObjectMapper objectMapper = new ObjectMapper();
 
-		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
-			.header("Content-Type", "application/json");
+		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder();
 
 		private AsyncHttpRequestCustomizer httpRequestCustomizer = AsyncHttpRequestCustomizer.NOOP;
 
@@ -540,6 +539,7 @@ private Mono> sendHttpPost(final String endpoint, final Str
 		return Mono.defer(() -> {
 			var builder = this.requestBuilder.copy()
 				.uri(requestUri)
+				.header("Content-Type", "application/json")
 				.header(MCP_PROTOCOL_VERSION_HEADER_NAME, MCP_PROTOCOL_VERSION)
 				.POST(HttpRequest.BodyPublishers.ofString(body));
 			return Mono.from(this.httpRequestCustomizer.customize(builder, "POST", requestUri, body));

From 336f2024e77d9fea4a52cbfdaa1abf44de95bfff Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Tue, 26 Aug 2025 10:30:31 +0200
Subject: [PATCH 054/125] feat: implement demand-based request handling in
 ResponseSubscribers (#516)

- Add hasRequestedDemand volatile boolean flag to AggregateSubscriber and BodilessResponseLineSubscriber
- Modify hookOnSubscribe to request Long.MAX_VALUE only on first demand request
- Guard event emission in hookOnComplete with hasRequestedDemand check
- Prevents unnecessary data processing when no downstream demand exists
- Improves backpressure handling and resource efficiency

Signed-off-by: Christian Tzolov 
---
 .../client/transport/ResponseSubscribers.java | 36 ++++++++++++++-----
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
index 945aeef78..29dc23c35 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
@@ -223,6 +223,8 @@ static class AggregateSubscriber extends BaseSubscriber {
 		 */
 		private ResponseInfo responseInfo;
 
+		volatile boolean hasRequestedDemand = false;
+
 		/**
 		 * Creates a new JsonLineSubscriber that will emit parsed JSON-RPC messages.
 		 * @param sink the {@link FluxSink} to emit parsed {@link ResponseEvent} objects
@@ -236,7 +238,13 @@ public AggregateSubscriber(ResponseInfo responseInfo, FluxSink si
 
 		@Override
 		protected void hookOnSubscribe(Subscription subscription) {
-			sink.onRequest(subscription::request);
+
+			sink.onRequest(n -> {
+				if (!hasRequestedDemand) {
+					subscription.request(Long.MAX_VALUE);
+				}
+				hasRequestedDemand = true;
+			});
 
 			// Register disposal callback to cancel subscription when Flux is disposed
 			sink.onDispose(subscription::cancel);
@@ -249,8 +257,11 @@ protected void hookOnNext(String line) {
 
 		@Override
 		protected void hookOnComplete() {
-			String data = this.eventBuilder.toString();
-			this.sink.next(new AggregateResponseEvent(responseInfo, data));
+
+			if (hasRequestedDemand) {
+				String data = this.eventBuilder.toString();
+				this.sink.next(new AggregateResponseEvent(responseInfo, data));
+			}
 
 			this.sink.complete();
 		}
@@ -271,6 +282,8 @@ static class BodilessResponseLineSubscriber extends BaseSubscriber {
 
 		private final ResponseInfo responseInfo;
 
+		volatile boolean hasRequestedDemand = false;
+
 		public BodilessResponseLineSubscriber(ResponseInfo responseInfo, FluxSink sink) {
 			this.sink = sink;
 			this.responseInfo = responseInfo;
@@ -280,7 +293,10 @@ public BodilessResponseLineSubscriber(ResponseInfo responseInfo, FluxSink {
-				subscription.request(n);
+				if (!hasRequestedDemand) {
+					subscription.request(Long.MAX_VALUE);
+				}
+				hasRequestedDemand = true;
 			});
 
 			// Register disposal callback to cancel subscription when Flux is disposed
@@ -291,11 +307,13 @@ protected void hookOnSubscribe(Subscription subscription) {
 
 		@Override
 		protected void hookOnComplete() {
-			// emit dummy event to be able to inspect the response info
-			// this is a shortcut allowing for a more streamlined processing using
-			// operator composition instead of having to deal with the CompletableFuture
-			// along the Subscriber for inspecting the result
-			this.sink.next(new DummyEvent(responseInfo));
+			if (hasRequestedDemand) {
+				// emit dummy event to be able to inspect the response info
+				// this is a shortcut allowing for a more streamlined processing using
+				// operator composition instead of having to deal with the
+				// CompletableFuture along the Subscriber for inspecting the result
+				this.sink.next(new DummyEvent(responseInfo));
+			}
 			this.sink.complete();
 		}
 

From 9c9e2ebdf793628fd783010e52554703ebe1f31c Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Tue, 26 Aug 2025 12:48:42 +0200
Subject: [PATCH 055/125] fix: disable logging capabilities for stateless
 servers (#517)

Remove LoggingCapabilities from McpStatelessServerFeatures.Async constructor
as stateless servers do not support setLogging operations. This aligns the
async implementation with the sync implementation which already has logging
disabled.

Follows up on #463

Signed-off-by: Christian Tzolov 
---
 .../server/McpStatelessServerFeatures.java                   | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
index 8be59a779..60c1dbb65 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
@@ -67,10 +67,7 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
 			this.serverCapabilities = (serverCapabilities != null) ? serverCapabilities
 					: new McpSchema.ServerCapabilities(null, // completions
 							null, // experimental
-							new McpSchema.ServerCapabilities.LoggingCapabilities(), // Enable
-																					// logging
-																					// by
-																					// default
+							null, // currently statless server doesn't support set logging
 							!Utils.isEmpty(prompts) ? new McpSchema.ServerCapabilities.PromptCapabilities(false) : null,
 							!Utils.isEmpty(resources)
 									? new McpSchema.ServerCapabilities.ResourceCapabilities(false, false) : null,

From b4fef5241fa81dda87138c98566014a090250f06 Mon Sep 17 00:00:00 2001
From: Kevin Stanton 
Date: Sun, 10 Aug 2025 00:18:05 -0500
Subject: [PATCH 056/125] feat: Add transport context extraction support to all
 MCP servers (#477)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add McpTransportContextExtractor to WebFlux/WebMVC SSE and Streamable transport providers
- Enable extraction of HTTP transport metadata (headers, etc.) for use during request processing
- Pass transport context through reactive context chain using McpTransportContext.KEY
- Add contextExtractor() builder methods for configuring custom extractors
- Update HttpServlet transport providers with same context extraction capability
- Modify McpServerSession to properly propagate transport context to handlers
- Add test coverage with TEST_CONTEXT_EXTRACTOR in integration tests

This allows MCP feature implementations to access HTTP transport level metadata
that was present at request time, enabling use cases like authentication,
request tracing, and custom header processing.

Signed-off-by: Christian Tzolov 

Co-authored-by: Christian Tzolov 
Co-authored-by: Dariusz Jędrzejczyk 
---
 .../WebFluxSseServerTransportProvider.java    | 57 ++++++++++++++++-
 ...FluxStreamableServerTransportProvider.java | 13 +++-
 .../WebFluxSseIntegrationTests.java           |  8 +++
 .../WebFluxStreamableIntegrationTests.java    |  8 +++
 .../WebMvcSseServerTransportProvider.java     | 60 ++++++++++++++++-
 .../server/WebMvcSseIntegrationTests.java     |  7 ++
 .../WebMvcSseSyncServerTransportTests.java    |  5 +-
 .../WebMvcStreamableIntegrationTests.java     |  7 ++
 ...stractMcpClientServerIntegrationTests.java | 63 +++++++++++++++++-
 ...HttpServletSseServerTransportProvider.java | 56 +++++++++++++++-
 .../spec/McpServerSession.java                | 36 ++++++++---
 ...stractMcpClientServerIntegrationTests.java | 64 ++++++++++++++++++-
 .../HttpServletSseIntegrationTests.java       |  7 ++
 ...HttpServletStreamableIntegrationTests.java |  7 ++
 14 files changed, 374 insertions(+), 24 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index aaf7bab46..ead7380f0 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -11,6 +11,10 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpServerSession;
@@ -115,6 +119,8 @@ public class WebFluxSseServerTransportProvider implements McpServerTransportProv
 	 */
 	private final ConcurrentHashMap sessions = new ConcurrentHashMap<>();
 
+	private McpTransportContextExtractor contextExtractor;
+
 	/**
 	 * Flag indicating if the transport is shutting down.
 	 */
@@ -194,15 +200,38 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseU
 	@Deprecated
 	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval) {
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
+				(serverRequest, context) -> context);
+	}
+
+	/**
+	 * Constructs a new WebFlux SSE server transport provider instance.
+	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * of MCP messages. Must not be null.
+	 * @param baseUrl webflux message base path
+	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
+	 * messages. This endpoint will be communicated to clients during SSE connection
+	 * setup. Must not be null.
+	 * @param sseEndpoint The SSE endpoint path. Must not be null.
+	 * @param keepAliveInterval The interval for sending keep-alive pings to clients.
+	 * @param contextExtractor The context extractor to use for extracting MCP transport
+	 * context from HTTP requests. Must not be null.
+	 * @throws IllegalArgumentException if either parameter is null
+	 */
+	private WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+			String sseEndpoint, Duration keepAliveInterval,
+			McpTransportContextExtractor contextExtractor) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.notNull(baseUrl, "Message base path must not be null");
 		Assert.notNull(messageEndpoint, "Message endpoint must not be null");
 		Assert.notNull(sseEndpoint, "SSE endpoint must not be null");
+		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
 		this.objectMapper = objectMapper;
 		this.baseUrl = baseUrl;
 		this.messageEndpoint = messageEndpoint;
 		this.sseEndpoint = sseEndpoint;
+		this.contextExtractor = contextExtractor;
 		this.routerFunction = RouterFunctions.route()
 			.GET(this.sseEndpoint, this::handleSseConnection)
 			.POST(this.messageEndpoint, this::handleMessage)
@@ -315,6 +344,8 @@ private Mono handleSseConnection(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
 		}
 
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
 		return ServerResponse.ok()
 			.contentType(MediaType.TEXT_EVENT_STREAM)
 			.body(Flux.>create(sink -> {
@@ -336,7 +367,7 @@ private Mono handleSseConnection(ServerRequest request) {
 					logger.debug("Session {} cancelled", sessionId);
 					sessions.remove(sessionId);
 				});
-			}), ServerSentEvent.class);
+			}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)), ServerSentEvent.class);
 	}
 
 	/**
@@ -370,6 +401,8 @@ private Mono handleMessage(ServerRequest request) {
 				.bodyValue(new McpError("Session not found: " + request.queryParam("sessionId").get()));
 		}
 
+		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+
 		return request.bodyToMono(String.class).flatMap(body -> {
 			try {
 				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
@@ -386,7 +419,7 @@ private Mono handleMessage(ServerRequest request) {
 				logger.error("Failed to deserialize message: {}", e.getMessage());
 				return ServerResponse.badRequest().bodyValue(new McpError("Invalid message format"));
 			}
-		});
+		}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext));
 	}
 
 	private class WebFluxMcpSessionTransport implements McpServerTransport {
@@ -458,6 +491,8 @@ public static class Builder {
 
 		private Duration keepAliveInterval;
 
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
 		/**
 		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
@@ -519,6 +554,22 @@ public Builder keepAliveInterval(Duration keepAliveInterval) {
 			return this;
 		}
 
+		/**
+		 * Sets the context extractor that allows providing the MCP feature
+		 * implementations to inspect HTTP transport level metadata that was present at
+		 * HTTP request processing time. This allows to extract custom headers and other
+		 * useful data for use during execution later on in the process.
+		 * @param contextExtractor The contextExtractor to fill in a
+		 * {@link McpTransportContext}.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "contextExtractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
 		/**
 		 * Builds a new instance of {@link WebFluxSseServerTransportProvider} with the
 		 * configured settings.
@@ -530,7 +581,7 @@ public WebFluxSseServerTransportProvider build() {
 			Assert.notNull(messageEndpoint, "Message endpoint must be set");
 
 			return new WebFluxSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
-					keepAliveInterval);
+					keepAliveInterval, contextExtractor);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index f3f6c2c33..963a50249 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -191,7 +191,9 @@ private Mono handleGet(ServerRequest request) {
 				String lastId = request.headers().asHttpHeaders().getFirst(HttpHeaders.LAST_EVENT_ID);
 				return ServerResponse.ok()
 					.contentType(MediaType.TEXT_EVENT_STREAM)
-					.body(session.replay(lastId), ServerSentEvent.class);
+					.body(session.replay(lastId)
+						.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)),
+							ServerSentEvent.class);
 			}
 
 			return ServerResponse.ok()
@@ -202,7 +204,9 @@ private Mono handleGet(ServerRequest request) {
 					McpStreamableServerSession.McpStreamableServerSessionStream listeningStream = session
 						.listeningStream(sessionTransport);
 					sink.onDispose(listeningStream::close);
-				}), ServerSentEvent.class);
+					// TODO Clarify why the outer context is not present in the
+					// Flux.create sink?
+				}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)), ServerSentEvent.class);
 
 		}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext));
 	}
@@ -282,7 +286,10 @@ else if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
 								return true;
 							}).contextWrite(sink.contextView()).subscribe();
 							sink.onCancel(streamSubscription);
-						}), ServerSentEvent.class);
+							// TODO Clarify why the outer context is not present in the
+							// Flux.create sink?
+						}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)),
+								ServerSentEvent.class);
 				}
 				else {
 					return ServerResponse.badRequest().bodyValue(new McpError("Unknown message type"));
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index 6140fe489..c8dc6e90b 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -13,6 +13,7 @@
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.server.RouterFunctions;
+import org.springframework.web.reactive.function.server.ServerRequest;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
@@ -22,6 +23,7 @@
 import io.modelcontextprotocol.server.McpServer;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SingleSessionSyncSpecification;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.server.TestUtil;
 import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
 import reactor.netty.DisposableServer;
@@ -40,6 +42,11 @@ class WebFluxSseIntegrationTests extends AbstractMcpClientServerIntegrationTests
 
 	private WebFluxSseServerTransportProvider mcpServerTransportProvider;
 
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
+		tc.put("important", "value");
+		return tc;
+	};
+
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 
@@ -75,6 +82,7 @@ public void before() {
 			.objectMapper(new ObjectMapper())
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
+			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 			.build();
 
 		HttpHandler httpHandler = RouterFunctions.toHttpHandler(mcpServerTransportProvider.getRouterFunction());
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
index 9eba0e57c..a7aac0f1e 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -13,6 +13,7 @@
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.server.RouterFunctions;
+import org.springframework.web.reactive.function.server.ServerRequest;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
@@ -22,6 +23,7 @@
 import io.modelcontextprotocol.server.McpServer;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.server.TestUtil;
 import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
 import reactor.netty.DisposableServer;
@@ -38,6 +40,11 @@ class WebFluxStreamableIntegrationTests extends AbstractMcpClientServerIntegrati
 
 	private WebFluxStreamableServerTransportProvider mcpStreamableServerTransportProvider;
 
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
+		tc.put("important", "value");
+		return tc;
+	};
+
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 
@@ -71,6 +78,7 @@ public void before() {
 		this.mcpStreamableServerTransportProvider = WebFluxStreamableServerTransportProvider.builder()
 			.objectMapper(new ObjectMapper())
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
+			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 			.build();
 
 		HttpHandler httpHandler = RouterFunctions
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index ff452ca74..6e92cf10c 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -13,6 +13,10 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpServerTransport;
@@ -106,6 +110,8 @@ public class WebMvcSseServerTransportProvider implements McpServerTransportProvi
 	 */
 	private final ConcurrentHashMap sessions = new ConcurrentHashMap<>();
 
+	private McpTransportContextExtractor contextExtractor;
+
 	/**
 	 * Flag indicating if the transport is shutting down.
 	 */
@@ -177,7 +183,7 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUr
 	 * messages via HTTP POST. This endpoint will be communicated to clients through the
 	 * SSE connection's initial endpoint event.
 	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
-	 * * @param keepAliveInterval The interval for sending keep-alive messages to
+	 * @param keepAliveInterval The interval for sending keep-alive messages to clients.
 	 * @throws IllegalArgumentException if any parameter is null
 	 * @deprecated Use the builder {@link #builder()} instead for better configuration
 	 * options.
@@ -185,15 +191,39 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUr
 	@Deprecated
 	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval) {
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
+				(serverRequest, context) -> context);
+	}
+
+	/**
+	 * Constructs a new WebMvcSseServerTransportProvider instance.
+	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * of messages.
+	 * @param baseUrl The base URL for the message endpoint, used to construct the full
+	 * endpoint URL for clients.
+	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
+	 * messages via HTTP POST. This endpoint will be communicated to clients through the
+	 * SSE connection's initial endpoint event.
+	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
+	 * @param keepAliveInterval The interval for sending keep-alive messages to clients.
+	 * @param contextExtractor The contextExtractor to fill in a
+	 * {@link McpTransportContext}.
+	 * @throws IllegalArgumentException if any parameter is null
+	 */
+	private WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+			String sseEndpoint, Duration keepAliveInterval,
+			McpTransportContextExtractor contextExtractor) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.notNull(baseUrl, "Message base URL must not be null");
 		Assert.notNull(messageEndpoint, "Message endpoint must not be null");
 		Assert.notNull(sseEndpoint, "SSE endpoint must not be null");
+		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
 		this.objectMapper = objectMapper;
 		this.baseUrl = baseUrl;
 		this.messageEndpoint = messageEndpoint;
 		this.sseEndpoint = sseEndpoint;
+		this.contextExtractor = contextExtractor;
 		this.routerFunction = RouterFunctions.route()
 			.GET(this.sseEndpoint, this::handleSseConnection)
 			.POST(this.messageEndpoint, this::handleMessage)
@@ -367,11 +397,17 @@ private ServerResponse handleMessage(ServerRequest request) {
 		}
 
 		try {
+			final McpTransportContext transportContext = this.contextExtractor.extract(request,
+					new DefaultMcpTransportContext());
+
 			String body = request.body(String.class);
 			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
 
 			// Process the message through the session's handle method
-			session.handle(message).block(); // Block for WebMVC compatibility
+			session.handle(message).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)).block(); // Block
+																														// for
+																														// WebMVC
+																														// compatibility
 
 			return ServerResponse.ok().build();
 		}
@@ -517,6 +553,8 @@ public static class Builder {
 
 		private Duration keepAliveInterval;
 
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
 		/**
 		 * Sets the JSON object mapper to use for message serialization/deserialization.
 		 * @param objectMapper The object mapper to use
@@ -576,6 +614,22 @@ public Builder keepAliveInterval(Duration keepAliveInterval) {
 			return this;
 		}
 
+		/**
+		 * Sets the context extractor that allows providing the MCP feature
+		 * implementations to inspect HTTP transport level metadata that was present at
+		 * HTTP request processing time. This allows to extract custom headers and other
+		 * useful data for use during execution later on in the process.
+		 * @param contextExtractor The contextExtractor to fill in a
+		 * {@link McpTransportContext}.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public Builder contextExtractor(McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "contextExtractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
 		/**
 		 * Builds a new instance of WebMvcSseServerTransportProvider with the configured
 		 * settings.
@@ -587,7 +641,7 @@ public WebMvcSseServerTransportProvider build() {
 				throw new IllegalStateException("MessageEndpoint must be set");
 			}
 			return new WebMvcSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
-					keepAliveInterval);
+					keepAliveInterval, contextExtractor);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index 5d048353c..8cb2973ed 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -17,6 +17,7 @@
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerRequest;
 import org.springframework.web.servlet.function.ServerResponse;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -39,6 +40,11 @@ class WebMvcSseIntegrationTests extends AbstractMcpClientServerIntegrationTests
 
 	private WebMvcSseServerTransportProvider mcpServerTransportProvider;
 
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
+		tc.put("important", "value");
+		return tc;
+	};
+
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 
@@ -60,6 +66,7 @@ public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
 			return WebMvcSseServerTransportProvider.builder()
 				.objectMapper(new ObjectMapper())
 				.messageEndpoint(MESSAGE_ENDPOINT)
+				.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 				.build();
 		}
 
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
index 7e49ddf3b..101a067ad 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
@@ -36,7 +36,10 @@ static class TestConfig {
 
 		@Bean
 		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
-			return new WebMvcSseServerTransportProvider(new ObjectMapper(), MESSAGE_ENDPOINT);
+			return WebMvcSseServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.messageEndpoint(MESSAGE_ENDPOINT)
+				.build();
 		}
 
 		@Bean
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
index 16012e7d9..2f4c651fd 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -15,6 +15,7 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.servlet.function.ServerRequest;
 import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 import org.springframework.web.servlet.function.RouterFunction;
 import org.springframework.web.servlet.function.ServerResponse;
@@ -39,6 +40,11 @@ class WebMvcStreamableIntegrationTests extends AbstractMcpClientServerIntegratio
 
 	private WebMvcStreamableServerTransportProvider mcpServerTransportProvider;
 
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
+		tc.put("important", "value");
+		return tc;
+	};
+
 	@Configuration
 	@EnableWebMvc
 	static class TestConfig {
@@ -47,6 +53,7 @@ static class TestConfig {
 		public WebMvcStreamableServerTransportProvider webMvcStreamableServerTransportProvider() {
 			return WebMvcStreamableServerTransportProvider.builder()
 				.objectMapper(new ObjectMapper())
+				.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 				.mcpEndpoint(MESSAGE_ENDPOINT)
 				.build();
 		}
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 8e041d91e..5246c1e2d 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -23,6 +23,7 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.BiFunction;
 import java.util.function.Function;
@@ -36,6 +37,7 @@
 import io.modelcontextprotocol.server.McpServerFeatures;
 import io.modelcontextprotocol.server.McpSyncServer;
 import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
@@ -55,6 +57,7 @@
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
+import io.modelcontextprotocol.util.Utils;
 import net.javacrumbs.jsonunit.core.Option;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
@@ -750,6 +753,7 @@ void testToolCallSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
+		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
@@ -763,7 +767,7 @@ void testToolCallSuccess(String clientType) {
 							.GET()
 							.build(), HttpResponse.BodyHandlers.ofString());
 					String responseBody = response.body();
-					assertThat(responseBody).isNotBlank();
+					responseBodyIsNullOrBlank.set(!Utils.hasText(responseBody));
 				}
 				catch (Exception e) {
 					e.printStackTrace();
@@ -786,6 +790,7 @@ void testToolCallSuccess(String clientType) {
 
 			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
+			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
 			assertThat(response).isNotNull().isEqualTo(callResponse);
 		}
 
@@ -829,6 +834,62 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 		mcpServer.close();
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testToolCallSuccessWithTranportContextExtraction(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var transportContextIsNull = new AtomicBoolean(false);
+		var transportContextIsEmpty = new AtomicBoolean(false);
+		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
+
+		var expectedCallResponse = new McpSchema.CallToolResult(
+				List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=value")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				McpTransportContext transportContext = exchange.transportContext();
+				transportContextIsNull.set(transportContext == null);
+				transportContextIsEmpty.set(transportContext.equals(McpTransportContext.EMPTY));
+				String ctxValue = (String) transportContext.get("important");
+
+				try {
+					String responseBody = "TOOL RESPONSE";
+					responseBodyIsNullOrBlank.set(!Utils.hasText(responseBody));
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+
+				return new McpSchema.CallToolResult(
+						List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=" + ctxValue)), null);
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(transportContextIsNull.get()).isFalse();
+			assertThat(transportContextIsEmpty.get()).isFalse();
+			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
+			assertThat(response).isNotNull().isEqualTo(expectedCallResponse);
+		}
+
+		mcpServer.close();
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testToolListChangeHandlingSuccess(String clientType) {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index ceeea31b1..582120e3f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -16,6 +16,9 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpServerSession;
@@ -102,6 +105,8 @@ public class HttpServletSseServerTransportProvider extends HttpServlet implement
 	/** Map of active client sessions, keyed by session ID */
 	private final Map sessions = new ConcurrentHashMap<>();
 
+	private McpTransportContextExtractor contextExtractor;
+
 	/** Flag indicating if the transport is in the process of shutting down */
 	private final AtomicBoolean isClosing = new AtomicBoolean(false);
 
@@ -144,7 +149,7 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String m
 	@Deprecated
 	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null);
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null, (serverRequest, context) -> context);
 	}
 
 	/**
@@ -163,11 +168,38 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String b
 	@Deprecated
 	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval) {
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
+				(serverRequest, context) -> context);
+	}
+
+	/**
+	 * Creates a new HttpServletSseServerTransportProvider instance with a custom SSE
+	 * endpoint.
+	 * @param objectMapper The JSON object mapper to use for message
+	 * serialization/deserialization
+	 * @param baseUrl The base URL for the server transport
+	 * @param messageEndpoint The endpoint path where clients will send their messages
+	 * @param sseEndpoint The endpoint path where clients will establish SSE connections
+	 * @param keepAliveInterval The interval for keep-alive pings, or null to disable
+	 * keep-alive functionality
+	 * @param contextExtractor The extractor for transport context from the request.
+	 * @deprecated Use the builder {@link #builder()} instead for better configuration
+	 * options.
+	 */
+	private HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+			String sseEndpoint, Duration keepAliveInterval,
+			McpTransportContextExtractor contextExtractor) {
+
+		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(messageEndpoint, "messageEndpoint must not be null");
+		Assert.notNull(sseEndpoint, "sseEndpoint must not be null");
+		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
 		this.objectMapper = objectMapper;
 		this.baseUrl = baseUrl;
 		this.messageEndpoint = messageEndpoint;
 		this.sseEndpoint = sseEndpoint;
+		this.contextExtractor = contextExtractor;
 
 		if (keepAliveInterval != null) {
 
@@ -339,10 +371,13 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 				body.append(line);
 			}
 
+			final McpTransportContext transportContext = this.contextExtractor.extract(request,
+					new DefaultMcpTransportContext());
 			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body.toString());
 
 			// Process the message through the session's handle method
-			session.handle(message).block(); // Block for Servlet compatibility
+			// Block for Servlet compatibility
+			session.handle(message).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)).block();
 
 			response.setStatus(HttpServletResponse.SC_OK);
 		}
@@ -534,6 +569,8 @@ public static class Builder {
 
 		private String sseEndpoint = DEFAULT_SSE_ENDPOINT;
 
+		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+
 		private Duration keepAliveInterval;
 
 		/**
@@ -583,6 +620,19 @@ public Builder sseEndpoint(String sseEndpoint) {
 			return this;
 		}
 
+		/**
+		 * Sets the context extractor for extracting transport context from the request.
+		 * @param contextExtractor The context extractor to use. Must not be null.
+		 * @return this builder instance
+		 * @throws IllegalArgumentException if contextExtractor is null
+		 */
+		public HttpServletSseServerTransportProvider.Builder contextExtractor(
+				McpTransportContextExtractor contextExtractor) {
+			Assert.notNull(contextExtractor, "Context extractor must not be null");
+			this.contextExtractor = contextExtractor;
+			return this;
+		}
+
 		/**
 		 * Sets the interval for keep-alive pings.
 		 * 

@@ -609,7 +659,7 @@ public HttpServletSseServerTransportProvider build() {
 				throw new IllegalStateException("MessageEndpoint must be set");
 			}
 			return new HttpServletSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
-					keepAliveInterval);
+					keepAliveInterval, contextExtractor);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index 62985dc17..e562ca012 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -198,7 +198,9 @@ public Mono sendNotification(String method, Object params) {
 	 * @return a Mono that completes when the message is processed
 	 */
 	public Mono handle(McpSchema.JSONRPCMessage message) {
-		return Mono.defer(() -> {
+		return Mono.deferContextual(ctx -> {
+			McpTransportContext transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+
 			// TODO handle errors for communication to without initialization happening
 			// first
 			if (message instanceof McpSchema.JSONRPCResponse response) {
@@ -214,7 +216,7 @@ public Mono handle(McpSchema.JSONRPCMessage message) {
 			}
 			else if (message instanceof McpSchema.JSONRPCRequest request) {
 				logger.debug("Received request: {}", request);
-				return handleIncomingRequest(request).onErrorResume(error -> {
+				return handleIncomingRequest(request, transportContext).onErrorResume(error -> {
 					var errorResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null,
 							new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
 									error.getMessage(), null));
@@ -227,7 +229,7 @@ else if (message instanceof McpSchema.JSONRPCNotification notification) {
 				// happening first
 				logger.debug("Received notification: {}", notification);
 				// TODO: in case of error, should the POST request be signalled?
-				return handleIncomingNotification(notification)
+				return handleIncomingNotification(notification, transportContext)
 					.doOnError(error -> logger.error("Error handling notification: {}", error.getMessage()));
 			}
 			else {
@@ -240,9 +242,11 @@ else if (message instanceof McpSchema.JSONRPCNotification notification) {
 	/**
 	 * Handles an incoming JSON-RPC request by routing it to the appropriate handler.
 	 * @param request The incoming JSON-RPC request
+	 * @param transportContext
 	 * @return A Mono containing the JSON-RPC response
 	 */
-	private Mono handleIncomingRequest(McpSchema.JSONRPCRequest request) {
+	private Mono handleIncomingRequest(McpSchema.JSONRPCRequest request,
+			McpTransportContext transportContext) {
 		return Mono.defer(() -> {
 			Mono resultMono;
 			if (McpSchema.METHOD_INITIALIZE.equals(request.method())) {
@@ -266,7 +270,8 @@ private Mono handleIncomingRequest(McpSchema.JSONRPCR
 									error.message(), error.data())));
 				}
 
-				resultMono = this.exchangeSink.asMono().flatMap(exchange -> handler.handle(exchange, request.params()));
+				resultMono = this.exchangeSink.asMono()
+					.flatMap(exchange -> handler.handle(copyExchange(exchange, transportContext), request.params()));
 			}
 			return resultMono
 				.map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), result, null))
@@ -280,16 +285,18 @@ private Mono handleIncomingRequest(McpSchema.JSONRPCR
 	/**
 	 * Handles an incoming JSON-RPC notification by routing it to the appropriate handler.
 	 * @param notification The incoming JSON-RPC notification
+	 * @param transportContext
 	 * @return A Mono that completes when the notification is processed
 	 */
-	private Mono handleIncomingNotification(McpSchema.JSONRPCNotification notification) {
+	private Mono handleIncomingNotification(McpSchema.JSONRPCNotification notification,
+			McpTransportContext transportContext) {
 		return Mono.defer(() -> {
 			if (McpSchema.METHOD_NOTIFICATION_INITIALIZED.equals(notification.method())) {
 				this.state.lazySet(STATE_INITIALIZED);
 				// FIXME: The session ID passed here is not the same as the one in the
 				// legacy SSE transport.
 				exchangeSink.tryEmitValue(new McpAsyncServerExchange(this.id, this, clientCapabilities.get(),
-						clientInfo.get(), McpTransportContext.EMPTY));
+						clientInfo.get(), transportContext));
 			}
 
 			var handler = notificationHandlers.get(notification.method());
@@ -297,10 +304,23 @@ private Mono handleIncomingNotification(McpSchema.JSONRPCNotification noti
 				logger.warn("No handler registered for notification method: {}", notification);
 				return Mono.empty();
 			}
-			return this.exchangeSink.asMono().flatMap(exchange -> handler.handle(exchange, notification.params()));
+			return this.exchangeSink.asMono()
+				.flatMap(exchange -> handler.handle(copyExchange(exchange, transportContext), notification.params()));
 		});
 	}
 
+	/**
+	 * This legacy implementation assumes an exchange is established upon the
+	 * initialization phase see: exchangeSink.tryEmitValue(...), which creates a cached
+	 * immutable exchange. Here, we create a new exchange and copy over everything from
+	 * that cached exchange, and use it for a single HTTP request, with the transport
+	 * context passed in.
+	 */
+	private McpAsyncServerExchange copyExchange(McpAsyncServerExchange exchange, McpTransportContext transportContext) {
+		return new McpAsyncServerExchange(exchange.sessionId(), this, exchange.getClientCapabilities(),
+				exchange.getClientInfo(), transportContext);
+	}
+
 	record MethodNotFoundError(String method, String message, Object data) {
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index e2adb340c..acaf0c8a9 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -23,6 +23,7 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.BiFunction;
 import java.util.function.Function;
@@ -51,6 +52,7 @@
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
+import io.modelcontextprotocol.util.Utils;
 import net.javacrumbs.jsonunit.core.Option;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
@@ -746,6 +748,7 @@ void testToolCallSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
+		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
@@ -759,7 +762,7 @@ void testToolCallSuccess(String clientType) {
 							.GET()
 							.build(), HttpResponse.BodyHandlers.ofString());
 					String responseBody = response.body();
-					assertThat(responseBody).isNotBlank();
+					responseBodyIsNullOrBlank.set(!Utils.hasText(responseBody));
 				}
 				catch (Exception e) {
 					e.printStackTrace();
@@ -782,6 +785,7 @@ void testToolCallSuccess(String clientType) {
 
 			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
+			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
 			assertThat(response).isNotNull().isEqualTo(callResponse);
 		}
 
@@ -825,6 +829,62 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 		mcpServer.close();
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testToolCallSuccessWithTranportContextExtraction(String clientType) {
+
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var transportContextIsNull = new AtomicBoolean(false);
+		var transportContextIsEmpty = new AtomicBoolean(false);
+		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
+
+		var expectedCallResponse = new McpSchema.CallToolResult(
+				List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=value")), null);
+		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.callHandler((exchange, request) -> {
+
+				McpTransportContext transportContext = exchange.transportContext();
+				transportContextIsNull.set(transportContext == null);
+				transportContextIsEmpty.set(transportContext.equals(McpTransportContext.EMPTY));
+				String ctxValue = (String) transportContext.get("important");
+
+				try {
+					String responseBody = "TOOL RESPONSE";
+					responseBodyIsNullOrBlank.set(!Utils.hasText(responseBody));
+				}
+				catch (Exception e) {
+					e.printStackTrace();
+				}
+
+				return new McpSchema.CallToolResult(
+						List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=" + ctxValue)), null);
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool1)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			assertThat(mcpClient.listTools().tools()).contains(tool1.tool());
+
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+
+			assertThat(transportContextIsNull.get()).isFalse();
+			assertThat(transportContextIsEmpty.get()).isFalse();
+			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
+			assertThat(response).isNotNull().isEqualTo(expectedCallResponse);
+		}
+
+		mcpServer.close();
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testToolListChangeHandlingSuccess(String clientType) {
@@ -946,7 +1006,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 		List receivedNotifications = new CopyOnWriteArrayList<>();
 
 		var clientBuilder = clientBuilders.get(clientType);
-		;
+
 		// Create server with a tool that sends logging notifications
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder()
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
index 823c28d8e..0f2991a9f 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
@@ -23,6 +23,7 @@
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
 import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import jakarta.servlet.http.HttpServletRequest;
 
 @Timeout(15)
 class HttpServletSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
@@ -42,6 +43,7 @@ public void before() {
 		// Create and configure the transport provider
 		mcpServerTransportProvider = HttpServletSseServerTransportProvider.builder()
 			.objectMapper(new ObjectMapper())
+			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
 			.build();
@@ -92,4 +94,9 @@ public void after() {
 	protected void prepareClients(int port, String mcpEndpoint) {
 	}
 
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
+		tc.put("important", "value");
+		return tc;
+	};
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 8a8675d95..2e9b4cbad 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -23,6 +23,7 @@
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
 import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import jakarta.servlet.http.HttpServletRequest;
 
 @Timeout(15)
 class HttpServletStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {
@@ -40,6 +41,7 @@ public void before() {
 		// Create and configure the transport provider
 		mcpServerTransportProvider = HttpServletStreamableServerTransportProvider.builder()
 			.objectMapper(new ObjectMapper())
+			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 			.mcpEndpoint(MESSAGE_ENDPOINT)
 			.keepAliveInterval(Duration.ofSeconds(1))
 			.build();
@@ -90,4 +92,9 @@ public void after() {
 	protected void prepareClients(int port, String mcpEndpoint) {
 	}
 
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
+		tc.put("important", "value");
+		return tc;
+	};
+
 }

From 95ba8e77ecd776f20d0ab55eb73dbd10279f257e Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Tue, 5 Aug 2025 15:49:20 +0200
Subject: [PATCH 057/125] refactor: move and rename HTTP request customizers to
 dedicated package (#453)

- Move Mcp(Async)HttpRequestCustomizer from client.transport to client.transport.customizer
- Rename (Async)HttpRequestCustomizer to Mcp(Async)HttpRequestCustomizer
- Add DelegatingMcpAsyncHttpRequestCustomizer and DelegatingMcpSyncHttpRequestCustomizer for composing multiple customizers
- Update all references across transport classes and tests
- Improve package organization and naming consistency with MCP prefix
---
 .../HttpClientSseClientTransport.java         | 24 ++++---
 .../HttpClientStreamableHttpTransport.java    | 22 +++---
 ...legatingMcpAsyncHttpRequestCustomizer.java | 38 +++++++++++
 ...elegatingMcpSyncHttpRequestCustomizer.java | 32 +++++++++
 .../McpAsyncHttpRequestCustomizer.java}       | 10 +--
 .../McpSyncHttpRequestCustomizer.java}        |  4 +-
 .../HttpClientSseClientTransportTests.java    |  8 ++-
 ...bleHttpTransportEmptyJsonResponseTest.java |  3 +-
 ...HttpClientStreamableHttpTransportTest.java |  6 +-
 ...tingMcpAsyncHttpRequestCustomizerTest.java | 67 +++++++++++++++++++
 ...atingMcpSyncHttpRequestCustomizerTest.java | 58 ++++++++++++++++
 11 files changed, 238 insertions(+), 34 deletions(-)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizer.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java
 rename mcp/src/main/java/io/modelcontextprotocol/client/transport/{AsyncHttpRequestCustomizer.java => customizer/McpAsyncHttpRequestCustomizer.java} (79%)
 rename mcp/src/main/java/io/modelcontextprotocol/client/transport/{SyncHttpRequestCustomizer.java => customizer/McpSyncHttpRequestCustomizer.java} (79%)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizerTest.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizerTest.java

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index a92f26c4e..74a3155e0 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -22,6 +22,8 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -112,7 +114,7 @@ public class HttpClientSseClientTransport implements McpClientTransport {
 	/**
 	 * Customizer to modify requests before they are executed.
 	 */
-	private final AsyncHttpRequestCustomizer httpRequestCustomizer;
+	private final McpAsyncHttpRequestCustomizer httpRequestCustomizer;
 
 	/**
 	 * Creates a new transport instance with default HTTP client and object mapper.
@@ -186,7 +188,7 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 	@Deprecated(forRemoval = true)
 	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
 			String sseEndpoint, ObjectMapper objectMapper) {
-		this(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper, AsyncHttpRequestCustomizer.NOOP);
+		this(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper, McpAsyncHttpRequestCustomizer.NOOP);
 	}
 
 	/**
@@ -202,7 +204,7 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 	 * @throws IllegalArgumentException if objectMapper, clientBuilder, or headers is null
 	 */
 	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
-			String sseEndpoint, ObjectMapper objectMapper, AsyncHttpRequestCustomizer httpRequestCustomizer) {
+			String sseEndpoint, ObjectMapper objectMapper, McpAsyncHttpRequestCustomizer httpRequestCustomizer) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.hasText(baseUri, "baseUri must not be empty");
 		Assert.hasText(sseEndpoint, "sseEndpoint must not be empty");
@@ -246,7 +248,7 @@ public static class Builder {
 
 		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder();
 
-		private AsyncHttpRequestCustomizer httpRequestCustomizer = AsyncHttpRequestCustomizer.NOOP;
+		private McpAsyncHttpRequestCustomizer httpRequestCustomizer = McpAsyncHttpRequestCustomizer.NOOP;
 
 		private Duration connectTimeout = Duration.ofSeconds(10);
 
@@ -352,16 +354,16 @@ public Builder objectMapper(ObjectMapper objectMapper) {
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}.
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}.
 		 * 

-		 * Do NOT use a blocking {@link SyncHttpRequestCustomizer} in a non-blocking
-		 * context. Use {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}
+		 * Do NOT use a blocking {@link McpSyncHttpRequestCustomizer} in a non-blocking
+		 * context. Use {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}
 		 * instead.
 		 * @param syncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder httpRequestCustomizer(SyncHttpRequestCustomizer syncHttpRequestCustomizer) {
-			this.httpRequestCustomizer = AsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
+		public Builder httpRequestCustomizer(McpSyncHttpRequestCustomizer syncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = McpAsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
 			return this;
 		}
 
@@ -370,13 +372,13 @@ public Builder httpRequestCustomizer(SyncHttpRequestCustomizer syncHttpRequestCu
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #httpRequestCustomizer(SyncHttpRequestCustomizer)}.
+		 * {@link #httpRequestCustomizer(McpSyncHttpRequestCustomizer)}.
 		 * 

 		 * Do NOT use a blocking implementation in a non-blocking context.
 		 * @param asyncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
+		public Builder asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
 			this.httpRequestCustomizer = asyncHttpRequestCustomizer;
 			return this;
 		}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index d8c49ae2f..a3815d0cf 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -25,6 +25,8 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
@@ -113,7 +115,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private final boolean resumableStreams;
 
-	private final AsyncHttpRequestCustomizer httpRequestCustomizer;
+	private final McpAsyncHttpRequestCustomizer httpRequestCustomizer;
 
 	private final AtomicReference activeSession = new AtomicReference<>();
 
@@ -123,7 +125,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private HttpClientStreamableHttpTransport(ObjectMapper objectMapper, HttpClient httpClient,
 			HttpRequest.Builder requestBuilder, String baseUri, String endpoint, boolean resumableStreams,
-			boolean openConnectionOnStartup, AsyncHttpRequestCustomizer httpRequestCustomizer) {
+			boolean openConnectionOnStartup, McpAsyncHttpRequestCustomizer httpRequestCustomizer) {
 		this.objectMapper = objectMapper;
 		this.httpClient = httpClient;
 		this.requestBuilder = requestBuilder;
@@ -598,7 +600,7 @@ public static class Builder {
 
 		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder();
 
-		private AsyncHttpRequestCustomizer httpRequestCustomizer = AsyncHttpRequestCustomizer.NOOP;
+		private McpAsyncHttpRequestCustomizer httpRequestCustomizer = McpAsyncHttpRequestCustomizer.NOOP;
 
 		private Duration connectTimeout = Duration.ofSeconds(10);
 
@@ -709,16 +711,16 @@ public Builder openConnectionOnStartup(boolean openConnectionOnStartup) {
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}.
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}.
 		 * 

-		 * Do NOT use a blocking {@link SyncHttpRequestCustomizer} in a non-blocking
-		 * context. Use {@link #asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer)}
+		 * Do NOT use a blocking {@link McpSyncHttpRequestCustomizer} in a non-blocking
+		 * context. Use {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}
 		 * instead.
 		 * @param syncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder httpRequestCustomizer(SyncHttpRequestCustomizer syncHttpRequestCustomizer) {
-			this.httpRequestCustomizer = AsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
+		public Builder httpRequestCustomizer(McpSyncHttpRequestCustomizer syncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = McpAsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
 			return this;
 		}
 
@@ -727,13 +729,13 @@ public Builder httpRequestCustomizer(SyncHttpRequestCustomizer syncHttpRequestCu
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #httpRequestCustomizer(SyncHttpRequestCustomizer)}.
+		 * {@link #httpRequestCustomizer(McpSyncHttpRequestCustomizer)}.
 		 * 

 		 * Do NOT use a blocking implementation in a non-blocking context.
 		 * @param asyncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder asyncHttpRequestCustomizer(AsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
+		public Builder asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
 			this.httpRequestCustomizer = asyncHttpRequestCustomizer;
 			return this;
 		}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizer.java
new file mode 100644
index 000000000..22ba6a265
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizer.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+package io.modelcontextprotocol.client.transport.customizer;
+
+import io.modelcontextprotocol.util.Assert;
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.util.List;
+import org.reactivestreams.Publisher;
+import reactor.core.publisher.Mono;
+
+/**
+ * Composable {@link McpAsyncHttpRequestCustomizer} that applies multiple customizers, in
+ * order.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+public class DelegatingMcpAsyncHttpRequestCustomizer implements McpAsyncHttpRequestCustomizer {
+
+	private final List customizers;
+
+	public DelegatingMcpAsyncHttpRequestCustomizer(List customizers) {
+		Assert.notNull(customizers, "Customizers must not be null");
+		this.customizers = customizers;
+	}
+
+	@Override
+	public Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
+			String body) {
+		var result = Mono.just(builder);
+		for (var customizer : this.customizers) {
+			result = result.flatMap(b -> Mono.from(customizer.customize(b, method, endpoint, body)));
+		}
+		return result;
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java
new file mode 100644
index 000000000..65649d916
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport.customizer;
+
+import io.modelcontextprotocol.util.Assert;
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.util.List;
+
+/**
+ * Composable {@link McpSyncHttpRequestCustomizer} that applies multiple customizers, in
+ * order.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+public class DelegatingMcpSyncHttpRequestCustomizer implements McpSyncHttpRequestCustomizer {
+
+	private final List delegates;
+
+	public DelegatingMcpSyncHttpRequestCustomizer(List customizers) {
+		Assert.notNull(customizers, "Customizers must not be null");
+		this.delegates = customizers;
+	}
+
+	@Override
+	public void customize(HttpRequest.Builder builder, String method, URI endpoint, String body) {
+		this.delegates.forEach(delegate -> delegate.customize(builder, method, endpoint, body));
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/AsyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpRequestCustomizer.java
similarity index 79%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/AsyncHttpRequestCustomizer.java
rename to mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpRequestCustomizer.java
index dee026d96..2f685c350 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/AsyncHttpRequestCustomizer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpRequestCustomizer.java
@@ -2,7 +2,7 @@
  * Copyright 2024-2025 the original author or authors.
  */
 
-package io.modelcontextprotocol.client.transport;
+package io.modelcontextprotocol.client.transport.customizer;
 
 import java.net.URI;
 import java.net.http.HttpRequest;
@@ -19,12 +19,12 @@
  *
  * @author Daniel Garnier-Moiroux
  */
-public interface AsyncHttpRequestCustomizer {
+public interface McpAsyncHttpRequestCustomizer {
 
 	Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
 			@Nullable String body);
 
-	AsyncHttpRequestCustomizer NOOP = new Noop();
+	McpAsyncHttpRequestCustomizer NOOP = new Noop();
 
 	/**
 	 * Wrap a sync implementation in an async wrapper.
@@ -32,14 +32,14 @@ Publisher customize(HttpRequest.Builder builder, String met
 	 * Do NOT wrap a blocking implementation for use in a non-blocking context. For a
 	 * blocking implementation, consider using {@link Schedulers#boundedElastic()}.
 	 */
-	static AsyncHttpRequestCustomizer fromSync(SyncHttpRequestCustomizer customizer) {
+	static McpAsyncHttpRequestCustomizer fromSync(McpSyncHttpRequestCustomizer customizer) {
 		return (builder, method, uri, body) -> Mono.fromSupplier(() -> {
 			customizer.customize(builder, method, uri, body);
 			return builder;
 		});
 	}
 
-	class Noop implements AsyncHttpRequestCustomizer {
+	class Noop implements McpAsyncHttpRequestCustomizer {
 
 		@Override
 		public Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/SyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java
similarity index 79%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/SyncHttpRequestCustomizer.java
rename to mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java
index 72b6e6c1b..8d2c4a698 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/SyncHttpRequestCustomizer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java
@@ -2,7 +2,7 @@
  * Copyright 2024-2025 the original author or authors.
  */
 
-package io.modelcontextprotocol.client.transport;
+package io.modelcontextprotocol.client.transport.customizer;
 
 import java.net.URI;
 import java.net.http.HttpRequest;
@@ -14,7 +14,7 @@
  *
  * @author Daniel Garnier-Moiroux
  */
-public interface SyncHttpRequestCustomizer {
+public interface McpSyncHttpRequestCustomizer {
 
 	void customize(HttpRequest.Builder builder, String method, URI endpoint, @Nullable String body);
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
index 46b9207f6..f5a5ecb12 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
@@ -15,6 +15,8 @@
 import java.util.function.Function;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCRequest;
 import org.junit.jupiter.api.AfterAll;
@@ -72,7 +74,7 @@ static class TestHttpClientSseClientTransport extends HttpClientSseClientTranspo
 		public TestHttpClientSseClientTransport(final String baseUri) {
 			super(HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build(),
 					HttpRequest.newBuilder().header("Content-Type", "application/json"), baseUri, "/sse",
-					new ObjectMapper(), AsyncHttpRequestCustomizer.NOOP);
+					new ObjectMapper(), McpAsyncHttpRequestCustomizer.NOOP);
 		}
 
 		public int getInboundMessageCount() {
@@ -389,7 +391,7 @@ void testChainedCustomizations() {
 
 	@Test
 	void testRequestCustomizer() {
-		var mockCustomizer = mock(SyncHttpRequestCustomizer.class);
+		var mockCustomizer = mock(McpSyncHttpRequestCustomizer.class);
 
 		// Create a transport with the customizer
 		var customizedTransport = HttpClientSseClientTransport.builder(host)
@@ -423,7 +425,7 @@ void testRequestCustomizer() {
 
 	@Test
 	void testAsyncRequestCustomizer() {
-		var mockCustomizer = mock(AsyncHttpRequestCustomizer.class);
+		var mockCustomizer = mock(McpAsyncHttpRequestCustomizer.class);
 		when(mockCustomizer.customize(any(), any(), any(), any()))
 			.thenAnswer(invocation -> Mono.just(invocation.getArguments()[0]));
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
index 8b3668671..e7d048ffe 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
@@ -22,6 +22,7 @@
 
 import com.sun.net.httpserver.HttpServer;
 
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.ProtocolVersions;
@@ -70,7 +71,7 @@ static void stopContainer() {
 	void testNotificationInitialized() throws URISyntaxException {
 
 		var uri = new URI(host + "/mcp");
-		var mockRequestCustomizer = mock(SyncHttpRequestCustomizer.class);
+		var mockRequestCustomizer = mock(McpSyncHttpRequestCustomizer.class);
 		var transport = HttpClientStreamableHttpTransport.builder(host)
 			.httpRequestCustomizer(mockRequestCustomizer)
 			.build();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index d645bb0b3..f08518c93 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.client.transport;
 
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
 import io.modelcontextprotocol.spec.McpSchema;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -63,7 +65,7 @@ void withTransport(HttpClientStreamableHttpTransport transport, Consumer Mono.just(invocation.getArguments()[0]));
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizerTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizerTest.java
new file mode 100644
index 000000000..f136cd65e
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizerTest.java
@@ -0,0 +1,67 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport.customizer;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * Tests for {@link DelegatingMcpAsyncHttpRequestCustomizer}.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+class DelegatingMcpAsyncHttpRequestCustomizerTest {
+
+	private static final URI TEST_URI = URI.create("https://example.com");
+
+	private final HttpRequest.Builder TEST_BUILDER = HttpRequest.newBuilder(TEST_URI);
+
+	@Test
+	void delegates() {
+		var mockCustomizer = mock(McpAsyncHttpRequestCustomizer.class);
+		when(mockCustomizer.customize(any(), any(), any(), any()))
+			.thenAnswer(invocation -> Mono.just(invocation.getArguments()[0]));
+		var customizer = new DelegatingMcpAsyncHttpRequestCustomizer(List.of(mockCustomizer));
+
+		StepVerifier.create(customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}"))
+			.expectNext(TEST_BUILDER)
+			.verifyComplete();
+
+		verify(mockCustomizer).customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}");
+	}
+
+	@Test
+	void delegatesInOrder() {
+		var customizer = new DelegatingMcpAsyncHttpRequestCustomizer(
+				List.of((builder, method, uri, body) -> Mono.just(builder.copy().header("x-test", "one")),
+						(builder, method, uri, body) -> Mono.just(builder.copy().header("x-test", "two"))));
+
+		var headers = Mono
+			.from(customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}"))
+			.map(HttpRequest.Builder::build)
+			.map(HttpRequest::headers)
+			.flatMapIterable(h -> h.allValues("x-test"));
+
+		StepVerifier.create(headers).expectNext("one").expectNext("two").verifyComplete();
+	}
+
+	@Test
+	void constructorRequiresNonNull() {
+		assertThatThrownBy(() -> new DelegatingMcpAsyncHttpRequestCustomizer(null))
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Customizers must not be null");
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizerTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizerTest.java
new file mode 100644
index 000000000..427472912
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizerTest.java
@@ -0,0 +1,58 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport.customizer;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.verify;
+
+/**
+ * Tests for {@link DelegatingMcpSyncHttpRequestCustomizer}.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+class DelegatingMcpSyncHttpRequestCustomizerTest {
+
+	private static final URI TEST_URI = URI.create("https://example.com");
+
+	private final HttpRequest.Builder TEST_BUILDER = HttpRequest.newBuilder(TEST_URI);
+
+	@Test
+	void delegates() {
+		var mockCustomizer = Mockito.mock(McpSyncHttpRequestCustomizer.class);
+		var customizer = new DelegatingMcpSyncHttpRequestCustomizer(List.of(mockCustomizer));
+
+		customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}");
+
+		verify(mockCustomizer).customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}");
+	}
+
+	@Test
+	void delegatesInOrder() {
+		var testHeaderName = "x-test";
+		var customizer = new DelegatingMcpSyncHttpRequestCustomizer(
+				List.of((builder, method, uri, body) -> builder.header(testHeaderName, "one"),
+						(builder, method, uri, body) -> builder.header(testHeaderName, "two")));
+
+		customizer.customize(TEST_BUILDER, "GET", TEST_URI, "");
+		var request = TEST_BUILDER.build();
+
+		assertThat(request.headers().allValues(testHeaderName)).containsExactly("one", "two");
+	}
+
+	@Test
+	void constructorRequiresNonNull() {
+		assertThatThrownBy(() -> new DelegatingMcpAsyncHttpRequestCustomizer(null))
+			.isInstanceOf(IllegalArgumentException.class)
+			.hasMessage("Customizers must not be null");
+	}
+
+}

From 629464b1d670c75333927b9b333ba532118119f3 Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Tue, 2 Sep 2025 11:09:40 +0200
Subject: [PATCH 058/125] Add McpTransportContext to McpSyncClient (#522)

* McpSyncClient: introduce McpTransportContext

- 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.
- Move McpTransportContext from server to common package for shared client/server usage
- Make McpTransportContext immutable by removing put() and copy() methods
- Add static create() factory method for creating contexts with predefined data
- Update McpTransportContextExtractor to return context instead of modifying one
- Replace DefaultMcpTransportContext mutable implementation with immutable version
- Update all transport implementations to use McpTransportContext.EMPTY as default
- Rename *HttpRequestCustomizer -> *HttpClientRequestCustomizer
- Add end-to-end McpTransportContextIntegrationTests
- This PR introduces a breaking change to the Sync/Async request
  customizers.

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../WebFluxSseServerTransportProvider.java    |  12 +-
 .../WebFluxStatelessServerTransport.java      |   8 +-
 ...FluxStreamableServerTransportProvider.java |  12 +-
 .../WebFluxSseIntegrationTests.java           |   8 +-
 .../WebFluxStreamableIntegrationTests.java    |   8 +-
 .../WebMvcSseServerTransportProvider.java     |  11 +-
 .../WebMvcStatelessServerTransport.java       |   8 +-
 ...bMvcStreamableServerTransportProvider.java |  12 +-
 .../server/WebMvcSseIntegrationTests.java     |   8 +-
 .../WebMvcStreamableIntegrationTests.java     |   8 +-
 ...stractMcpClientServerIntegrationTests.java |   2 +-
 .../client/McpClient.java                     |  25 +-
 .../client/McpSyncClient.java                 |  72 ++++--
 .../HttpClientSseClientTransport.java         |  40 +--
 .../HttpClientStreamableHttpTransport.java    |  42 +--
 ...gMcpAsyncHttpClientRequestCustomizer.java} |  20 +-
 ...ingMcpSyncHttpClientRequestCustomizer.java |  35 +++
 ...elegatingMcpSyncHttpRequestCustomizer.java |  32 ---
 ... McpAsyncHttpClientRequestCustomizer.java} |  19 +-
 .../McpSyncHttpClientRequestCustomizer.java   |  28 ++
 .../McpSyncHttpRequestCustomizer.java         |  21 --
 .../common/DefaultMcpTransportContext.java    |  45 ++++
 .../McpTransportContext.java                  |  26 +-
 .../DefaultMcpStatelessServerHandler.java     |   1 +
 .../server/DefaultMcpTransportContext.java    |  49 ----
 .../server/McpAsyncServerExchange.java        |   1 +
 .../server/McpServer.java                     |   1 +
 .../server/McpStatelessAsyncServer.java       |   1 +
 .../McpStatelessNotificationHandler.java      |   1 +
 .../server/McpStatelessRequestHandler.java    |   1 +
 .../server/McpStatelessServerFeatures.java    |   1 +
 .../server/McpStatelessServerHandler.java     |   1 +
 .../server/McpSyncServerExchange.java         |   1 +
 .../server/McpTransportContextExtractor.java  |  11 +-
 ...HttpServletSseServerTransportProvider.java |  13 +-
 .../HttpServletStatelessServerTransport.java  |   8 +-
 ...vletStreamableServerTransportProvider.java |  12 +-
 .../spec/McpServerSession.java                |   2 +-
 .../spec/McpStreamableServerSession.java      |   2 +-
 ...tpClientStreamableHttpSyncClientTests.java |  30 ++-
 .../client/HttpSseMcpSyncClientTests.java     |  35 ++-
 .../HttpClientSseClientTransportTests.java    |  47 +++-
 ...bleHttpTransportEmptyJsonResponseTest.java |   7 +-
 ...HttpClientStreamableHttpTransportTest.java |  30 ++-
 ...AsyncHttpClientRequestCustomizerTest.java} |  29 ++-
 ...pSyncHttpClientRequestCustomizerTest.java} |  25 +-
 .../McpTransportContextIntegrationTests.java  | 241 ++++++++++++++++++
 ...stractMcpClientServerIntegrationTests.java |   1 +
 .../HttpServletSseIntegrationTests.java       |   8 +-
 .../HttpServletStatelessIntegrationTests.java |   1 +
 ...HttpServletStreamableIntegrationTests.java |   8 +-
 .../server/McpAsyncServerExchangeTests.java   |   3 +-
 52 files changed, 746 insertions(+), 327 deletions(-)
 rename mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/{DelegatingMcpAsyncHttpRequestCustomizer.java => DelegatingMcpAsyncHttpClientRequestCustomizer.java} (58%)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java
 delete mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java
 rename mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/{McpAsyncHttpRequestCustomizer.java => McpAsyncHttpClientRequestCustomizer.java} (65%)
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java
 delete mode 100644 mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java
 create mode 100644 mcp/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java
 rename mcp/src/main/java/io/modelcontextprotocol/{server => common}/McpTransportContext.java (68%)
 delete mode 100644 mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
 rename mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/{DelegatingMcpAsyncHttpRequestCustomizerTest.java => DelegatingMcpAsyncHttpClientRequestCustomizerTest.java} (57%)
 rename mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/{DelegatingMcpSyncHttpRequestCustomizerTest.java => DelegatingMcpSyncHttpClientRequestCustomizerTest.java} (55%)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index ead7380f0..f64346265 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -12,8 +12,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
-import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -201,7 +200,7 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseU
 	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval) {
 		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
-				(serverRequest, context) -> context);
+				(serverRequest) -> McpTransportContext.EMPTY);
 	}
 
 	/**
@@ -344,7 +343,7 @@ private Mono handleSseConnection(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		return ServerResponse.ok()
 			.contentType(MediaType.TEXT_EVENT_STREAM)
@@ -401,7 +400,7 @@ private Mono handleMessage(ServerRequest request) {
 				.bodyValue(new McpError("Session not found: " + request.queryParam("sessionId").get()));
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		return request.bodyToMono(String.class).flatMap(body -> {
 			try {
@@ -491,7 +490,8 @@ public static class Builder {
 
 		private Duration keepAliveInterval;
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		/**
 		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
index 23fff25b3..1f3d4c3bf 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
@@ -5,13 +5,12 @@
 package io.modelcontextprotocol.server.transport;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpStatelessServerTransport;
-import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -97,7 +96,7 @@ private Mono handlePost(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
 		if (!(acceptHeaders.contains(MediaType.APPLICATION_JSON)
@@ -151,7 +150,8 @@ public static class Builder {
 
 		private String mcpEndpoint = "/mcp";
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		private Builder() {
 			// used by a static method
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index 963a50249..44d89eaeb 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -6,7 +6,7 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpError;
@@ -15,7 +15,6 @@
 import io.modelcontextprotocol.spec.McpStreamableServerTransport;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.ProtocolVersions;
-import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
 
@@ -166,7 +165,7 @@ private Mono handleGet(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		return Mono.defer(() -> {
 			List acceptHeaders = request.headers().asHttpHeaders().getAccept();
@@ -221,7 +220,7 @@ private Mono handlePost(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
 		if (!(acceptHeaders.contains(MediaType.APPLICATION_JSON)
@@ -309,7 +308,7 @@ private Mono handleDelete(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).bodyValue("Server is shutting down");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		return Mono.defer(() -> {
 			if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
@@ -402,7 +401,8 @@ public static class Builder {
 
 		private String mcpEndpoint = "/mcp";
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		private boolean disallowDelete;
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index c8dc6e90b..f8f0f7a3a 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -5,6 +5,7 @@
 package io.modelcontextprotocol;
 
 import java.time.Duration;
+import java.util.Map;
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
@@ -20,6 +21,7 @@
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SingleSessionSyncSpecification;
@@ -42,10 +44,8 @@ class WebFluxSseIntegrationTests extends AbstractMcpClientServerIntegrationTests
 
 	private WebFluxSseServerTransportProvider mcpServerTransportProvider;
 
-	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
-		tc.put("important", "value");
-		return tc;
-	};
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r) -> McpTransportContext
+		.create(Map.of("important", "value"));
 
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
index a7aac0f1e..933ddf39d 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -5,6 +5,7 @@
 package io.modelcontextprotocol;
 
 import java.time.Duration;
+import java.util.Map;
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
@@ -20,6 +21,7 @@
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
@@ -40,10 +42,8 @@ class WebFluxStreamableIntegrationTests extends AbstractMcpClientServerIntegrati
 
 	private WebFluxStreamableServerTransportProvider mcpStreamableServerTransportProvider;
 
-	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
-		tc.put("important", "value");
-		return tc;
-	};
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r) -> McpTransportContext
+		.create(Map.of("important", "value"));
 
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index 6e92cf10c..85373b6fe 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -14,8 +14,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
-import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -192,7 +191,7 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUr
 	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval) {
 		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
-				(serverRequest, context) -> context);
+				(serverRequest) -> McpTransportContext.EMPTY);
 	}
 
 	/**
@@ -397,8 +396,7 @@ private ServerResponse handleMessage(ServerRequest request) {
 		}
 
 		try {
-			final McpTransportContext transportContext = this.contextExtractor.extract(request,
-					new DefaultMcpTransportContext());
+			final McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 			String body = request.body(String.class);
 			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
@@ -553,7 +551,8 @@ public static class Builder {
 
 		private Duration keepAliveInterval;
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		/**
 		 * Sets the JSON object mapper to use for message serialization/deserialization.
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
index fef1920fc..fc2da0439 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
@@ -5,13 +5,12 @@
 package io.modelcontextprotocol.server.transport;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpStatelessServerTransport;
-import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -101,7 +100,7 @@ private ServerResponse handlePost(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		List acceptHeaders = request.headers().asHttpHeaders().getAccept();
 		if (!(acceptHeaders.contains(MediaType.APPLICATION_JSON)
@@ -176,7 +175,8 @@ public static class Builder {
 
 		private String mcpEndpoint = "/mcp";
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		private Builder() {
 			// used by a static method
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index fa51a0130..3cc104dd4 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -23,8 +23,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
-import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpError;
@@ -238,7 +237,7 @@ private ServerResponse handleGet(ServerRequest request) {
 			return ServerResponse.badRequest().body("Invalid Accept header. Expected TEXT_EVENT_STREAM");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
 			return ServerResponse.badRequest().body("Session ID required in mcp-session-id header");
@@ -322,7 +321,7 @@ private ServerResponse handlePost(ServerRequest request) {
 				.body(new McpError("Invalid Accept headers. Expected TEXT_EVENT_STREAM and APPLICATION_JSON"));
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		try {
 			String body = request.body(String.class);
@@ -431,7 +430,7 @@ private ServerResponse handleDelete(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.METHOD_NOT_ALLOWED).build();
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
 			return ServerResponse.badRequest().body("Session ID required in mcp-session-id header");
@@ -604,7 +603,8 @@ public static class Builder {
 
 		private boolean disallowDelete = false;
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		private Duration keepAliveInterval;
 
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index 8cb2973ed..18a9d0063 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -6,6 +6,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import java.time.Duration;
+import java.util.Map;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
@@ -26,6 +27,7 @@
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SingleSessionSyncSpecification;
 import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
@@ -40,10 +42,8 @@ class WebMvcSseIntegrationTests extends AbstractMcpClientServerIntegrationTests
 
 	private WebMvcSseServerTransportProvider mcpServerTransportProvider;
 
-	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
-		tc.put("important", "value");
-		return tc;
-	};
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = r -> McpTransportContext
+		.create(Map.of("important", "value"));
 
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
index 2f4c651fd..3f1716f89 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -6,6 +6,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import java.time.Duration;
+import java.util.Map;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
@@ -26,6 +27,7 @@
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
 import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
@@ -40,10 +42,8 @@ class WebMvcStreamableIntegrationTests extends AbstractMcpClientServerIntegratio
 
 	private WebMvcStreamableServerTransportProvider mcpServerTransportProvider;
 
-	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
-		tc.put("important", "value");
-		return tc;
-	};
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = r -> McpTransportContext
+		.create(Map.of("important", "value"));
 
 	@Configuration
 	@EnableWebMvc
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 5246c1e2d..300f0b534 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -33,11 +33,11 @@
 import org.junit.jupiter.params.provider.ValueSource;
 
 import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer;
 import io.modelcontextprotocol.server.McpServerFeatures;
 import io.modelcontextprotocol.server.McpSyncServer;
 import io.modelcontextprotocol.server.McpSyncServerExchange;
-import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java
index c8af28ac1..534879f2c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java
@@ -11,10 +11,11 @@
 import java.util.Map;
 import java.util.function.Consumer;
 import java.util.function.Function;
+import java.util.function.Supplier;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpTransport;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
 import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
@@ -22,6 +23,7 @@
 import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
 import io.modelcontextprotocol.spec.McpSchema.Implementation;
 import io.modelcontextprotocol.spec.McpSchema.Root;
+import io.modelcontextprotocol.spec.McpTransport;
 import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Mono;
 
@@ -183,6 +185,8 @@ class SyncSpec {
 
 		private Function elicitationHandler;
 
+		private Supplier contextProvider = () -> McpTransportContext.EMPTY;
+
 		private SyncSpec(McpClientTransport transport) {
 			Assert.notNull(transport, "Transport must not be null");
 			this.transport = transport;
@@ -409,6 +413,22 @@ public SyncSpec progressConsumers(List>
 			return this;
 		}
 
+		/**
+		 * Add a provider of {@link McpTransportContext}, providing a context before
+		 * calling any client operation. This allows to extract thread-locals and hand
+		 * them over to the underlying transport.
+		 * 

+		 * There is no direct equivalent in {@link AsyncSpec}. To achieve the same result,
+		 * append {@code contextWrite(McpTransportContext.KEY, context)} to any
+		 * {@link McpAsyncClient} call.
+		 * @param contextProvider A supplier to create a context
+		 * @return This builder for method chaining
+		 */
+		public SyncSpec transportContextProvider(Supplier contextProvider) {
+			this.contextProvider = contextProvider;
+			return this;
+		}
+
 		/**
 		 * Create an instance of {@link McpSyncClient} with the provided configurations or
 		 * sensible defaults.
@@ -423,7 +443,8 @@ public McpSyncClient build() {
 			McpClientFeatures.Async asyncFeatures = McpClientFeatures.Async.fromSync(syncFeatures);
 
 			return new McpSyncClient(
-					new McpAsyncClient(transport, this.requestTimeout, this.initializationTimeout, asyncFeatures));
+					new McpAsyncClient(transport, this.requestTimeout, this.initializationTimeout, asyncFeatures),
+					this.contextProvider);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
index 33784adcd..7fdaa8941 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
@@ -5,16 +5,19 @@
 package io.modelcontextprotocol.client;
 
 import java.time.Duration;
+import java.util.function.Supplier;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptRequest;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
 import io.modelcontextprotocol.spec.McpSchema.ListPromptsResult;
 import io.modelcontextprotocol.util.Assert;
+import reactor.core.publisher.Mono;
 
 /**
  * A synchronous client implementation for the Model Context Protocol (MCP) that wraps an
@@ -63,14 +66,20 @@ public class McpSyncClient implements AutoCloseable {
 
 	private final McpAsyncClient delegate;
 
+	private final Supplier contextProvider;
+
 	/**
 	 * Create a new McpSyncClient with the given delegate.
 	 * @param delegate the asynchronous kernel on top of which this synchronous client
 	 * provides a blocking API.
+	 * @param contextProvider the supplier of context before calling any non-blocking
+	 * operation on underlying delegate
 	 */
-	McpSyncClient(McpAsyncClient delegate) {
+	McpSyncClient(McpAsyncClient delegate, Supplier contextProvider) {
 		Assert.notNull(delegate, "The delegate can not be null");
+		Assert.notNull(contextProvider, "The contextProvider can not be null");
 		this.delegate = delegate;
+		this.contextProvider = contextProvider;
 	}
 
 	/**
@@ -177,14 +186,14 @@ 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();
+		return withProvidedContext(this.delegate.initialize()).block();
 	}
 
 	/**
 	 * Send a roots/list_changed notification.
 	 */
 	public void rootsListChangedNotification() {
-		this.delegate.rootsListChangedNotification().block();
+		withProvidedContext(this.delegate.rootsListChangedNotification()).block();
 	}
 
 	/**
@@ -206,7 +215,7 @@ public void removeRoot(String rootUri) {
 	 * @return
 	 */
 	public Object ping() {
-		return this.delegate.ping().block();
+		return withProvidedContext(this.delegate.ping()).block();
 	}
 
 	// --------------------------
@@ -224,7 +233,8 @@ public Object ping() {
 	 * Boolean indicating if the execution failed (true) or succeeded (false/absent)
 	 */
 	public McpSchema.CallToolResult callTool(McpSchema.CallToolRequest callToolRequest) {
-		return this.delegate.callTool(callToolRequest).block();
+		return withProvidedContext(this.delegate.callTool(callToolRequest)).block();
+
 	}
 
 	/**
@@ -234,7 +244,7 @@ public McpSchema.CallToolResult callTool(McpSchema.CallToolRequest callToolReque
 	 * pagination if more tools are available
 	 */
 	public McpSchema.ListToolsResult listTools() {
-		return this.delegate.listTools().block();
+		return withProvidedContext(this.delegate.listTools()).block();
 	}
 
 	/**
@@ -245,7 +255,8 @@ public McpSchema.ListToolsResult listTools() {
 	 * pagination if more tools are available
 	 */
 	public McpSchema.ListToolsResult listTools(String cursor) {
-		return this.delegate.listTools(cursor).block();
+		return withProvidedContext(this.delegate.listTools(cursor)).block();
+
 	}
 
 	// --------------------------
@@ -257,7 +268,8 @@ public McpSchema.ListToolsResult listTools(String cursor) {
 	 * @return The list of all resources result
 	 */
 	public McpSchema.ListResourcesResult listResources() {
-		return this.delegate.listResources().block();
+		return withProvidedContext(this.delegate.listResources()).block();
+
 	}
 
 	/**
@@ -266,7 +278,8 @@ public McpSchema.ListResourcesResult listResources() {
 	 * @return The list of resources result
 	 */
 	public McpSchema.ListResourcesResult listResources(String cursor) {
-		return this.delegate.listResources(cursor).block();
+		return withProvidedContext(this.delegate.listResources(cursor)).block();
+
 	}
 
 	/**
@@ -275,7 +288,8 @@ public McpSchema.ListResourcesResult listResources(String cursor) {
 	 * @return the resource content.
 	 */
 	public McpSchema.ReadResourceResult readResource(McpSchema.Resource resource) {
-		return this.delegate.readResource(resource).block();
+		return withProvidedContext(this.delegate.readResource(resource)).block();
+
 	}
 
 	/**
@@ -284,7 +298,8 @@ public McpSchema.ReadResourceResult readResource(McpSchema.Resource resource) {
 	 * @return the resource content.
 	 */
 	public McpSchema.ReadResourceResult readResource(McpSchema.ReadResourceRequest readResourceRequest) {
-		return this.delegate.readResource(readResourceRequest).block();
+		return withProvidedContext(this.delegate.readResource(readResourceRequest)).block();
+
 	}
 
 	/**
@@ -292,7 +307,8 @@ public McpSchema.ReadResourceResult readResource(McpSchema.ReadResourceRequest r
 	 * @return The list of all resource templates result.
 	 */
 	public McpSchema.ListResourceTemplatesResult listResourceTemplates() {
-		return this.delegate.listResourceTemplates().block();
+		return withProvidedContext(this.delegate.listResourceTemplates()).block();
+
 	}
 
 	/**
@@ -304,7 +320,8 @@ public McpSchema.ListResourceTemplatesResult listResourceTemplates() {
 	 * @return The list of resource templates result.
 	 */
 	public McpSchema.ListResourceTemplatesResult listResourceTemplates(String cursor) {
-		return this.delegate.listResourceTemplates(cursor).block();
+		return withProvidedContext(this.delegate.listResourceTemplates(cursor)).block();
+
 	}
 
 	/**
@@ -317,7 +334,8 @@ public McpSchema.ListResourceTemplatesResult listResourceTemplates(String cursor
 	 * subscribe to.
 	 */
 	public void subscribeResource(McpSchema.SubscribeRequest subscribeRequest) {
-		this.delegate.subscribeResource(subscribeRequest).block();
+		withProvidedContext(this.delegate.subscribeResource(subscribeRequest)).block();
+
 	}
 
 	/**
@@ -326,7 +344,8 @@ public void subscribeResource(McpSchema.SubscribeRequest subscribeRequest) {
 	 * to unsubscribe from.
 	 */
 	public void unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest) {
-		this.delegate.unsubscribeResource(unsubscribeRequest).block();
+		withProvidedContext(this.delegate.unsubscribeResource(unsubscribeRequest)).block();
+
 	}
 
 	// --------------------------
@@ -338,7 +357,7 @@ public void unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest)
 	 * @return The list of all prompts result.
 	 */
 	public ListPromptsResult listPrompts() {
-		return this.delegate.listPrompts().block();
+		return withProvidedContext(this.delegate.listPrompts()).block();
 	}
 
 	/**
@@ -347,11 +366,12 @@ public ListPromptsResult listPrompts() {
 	 * @return The list of prompts result.
 	 */
 	public ListPromptsResult listPrompts(String cursor) {
-		return this.delegate.listPrompts(cursor).block();
+		return withProvidedContext(this.delegate.listPrompts(cursor)).block();
+
 	}
 
 	public GetPromptResult getPrompt(GetPromptRequest getPromptRequest) {
-		return this.delegate.getPrompt(getPromptRequest).block();
+		return withProvidedContext(this.delegate.getPrompt(getPromptRequest)).block();
 	}
 
 	/**
@@ -359,7 +379,8 @@ public GetPromptResult getPrompt(GetPromptRequest getPromptRequest) {
 	 * @param loggingLevel the min logging level
 	 */
 	public void setLoggingLevel(McpSchema.LoggingLevel loggingLevel) {
-		this.delegate.setLoggingLevel(loggingLevel).block();
+		withProvidedContext(this.delegate.setLoggingLevel(loggingLevel)).block();
+
 	}
 
 	/**
@@ -369,7 +390,18 @@ public void setLoggingLevel(McpSchema.LoggingLevel loggingLevel) {
 	 * @return the completion result containing suggested values.
 	 */
 	public McpSchema.CompleteResult completeCompletion(McpSchema.CompleteRequest completeRequest) {
-		return this.delegate.completeCompletion(completeRequest).block();
+		return withProvidedContext(this.delegate.completeCompletion(completeRequest)).block();
+
+	}
+
+	/**
+	 * For a given action, on assembly, capture the "context" via the
+	 * {@link #contextProvider} and store it in the Reactor context.
+	 * @param action the action to perform
+	 * @return the result of the action
+	 */
+	private  Mono withProvidedContext(Mono action) {
+		return action.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, this.contextProvider.get()));
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index 74a3155e0..c2c74dcae 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -22,14 +22,15 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
-import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
 import io.modelcontextprotocol.spec.McpTransportException;
+import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
 import reactor.core.Disposable;
@@ -114,7 +115,7 @@ public class HttpClientSseClientTransport implements McpClientTransport {
 	/**
 	 * Customizer to modify requests before they are executed.
 	 */
-	private final McpAsyncHttpRequestCustomizer httpRequestCustomizer;
+	private final McpAsyncHttpClientRequestCustomizer httpRequestCustomizer;
 
 	/**
 	 * Creates a new transport instance with default HTTP client and object mapper.
@@ -188,7 +189,7 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 	@Deprecated(forRemoval = true)
 	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
 			String sseEndpoint, ObjectMapper objectMapper) {
-		this(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper, McpAsyncHttpRequestCustomizer.NOOP);
+		this(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper, McpAsyncHttpClientRequestCustomizer.NOOP);
 	}
 
 	/**
@@ -204,7 +205,7 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 	 * @throws IllegalArgumentException if objectMapper, clientBuilder, or headers is null
 	 */
 	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
-			String sseEndpoint, ObjectMapper objectMapper, McpAsyncHttpRequestCustomizer httpRequestCustomizer) {
+			String sseEndpoint, ObjectMapper objectMapper, McpAsyncHttpClientRequestCustomizer httpRequestCustomizer) {
 		Assert.notNull(objectMapper, "ObjectMapper must not be null");
 		Assert.hasText(baseUri, "baseUri must not be empty");
 		Assert.hasText(sseEndpoint, "sseEndpoint must not be empty");
@@ -248,7 +249,7 @@ public static class Builder {
 
 		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder();
 
-		private McpAsyncHttpRequestCustomizer httpRequestCustomizer = McpAsyncHttpRequestCustomizer.NOOP;
+		private McpAsyncHttpClientRequestCustomizer httpRequestCustomizer = McpAsyncHttpClientRequestCustomizer.NOOP;
 
 		private Duration connectTimeout = Duration.ofSeconds(10);
 
@@ -354,16 +355,17 @@ public Builder objectMapper(ObjectMapper objectMapper) {
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}.
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer)}.
 		 * 

-		 * Do NOT use a blocking {@link McpSyncHttpRequestCustomizer} in a non-blocking
-		 * context. Use {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}
+		 * Do NOT use a blocking {@link McpSyncHttpClientRequestCustomizer} in a
+		 * non-blocking context. Use
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer)}
 		 * instead.
 		 * @param syncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder httpRequestCustomizer(McpSyncHttpRequestCustomizer syncHttpRequestCustomizer) {
-			this.httpRequestCustomizer = McpAsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
+		public Builder httpRequestCustomizer(McpSyncHttpClientRequestCustomizer syncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = McpAsyncHttpClientRequestCustomizer.fromSync(syncHttpRequestCustomizer);
 			return this;
 		}
 
@@ -372,13 +374,13 @@ public Builder httpRequestCustomizer(McpSyncHttpRequestCustomizer syncHttpReques
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #httpRequestCustomizer(McpSyncHttpRequestCustomizer)}.
+		 * {@link #httpRequestCustomizer(McpSyncHttpClientRequestCustomizer)}.
 		 * 

 		 * Do NOT use a blocking implementation in a non-blocking context.
 		 * @param asyncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
+		public Builder asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer asyncHttpRequestCustomizer) {
 			this.httpRequestCustomizer = asyncHttpRequestCustomizer;
 			return this;
 		}
@@ -410,14 +412,15 @@ public HttpClientSseClientTransport build() {
 	public Mono connect(Function, Mono> handler) {
 		var uri = Utils.resolveUri(this.baseUri, this.sseEndpoint);
 
-		return Mono.defer(() -> {
+		return Mono.deferContextual(ctx -> {
 			var builder = requestBuilder.copy()
 				.uri(uri)
 				.header("Accept", "text/event-stream")
 				.header("Cache-Control", "no-cache")
 				.header(MCP_PROTOCOL_VERSION_HEADER_NAME, MCP_PROTOCOL_VERSION)
 				.GET();
-			return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null));
+			var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+			return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null, transportContext));
 		}).flatMap(requestBuilder -> Mono.create(sink -> {
 			Disposable connection = Flux.create(sseSink -> this.httpClient
 				.sendAsync(requestBuilder.build(),
@@ -538,13 +541,14 @@ private Mono serializeMessage(final JSONRPCMessage message) {
 
 	private Mono> sendHttpPost(final String endpoint, final String body) {
 		final URI requestUri = Utils.resolveUri(baseUri, endpoint);
-		return Mono.defer(() -> {
+		return Mono.deferContextual(ctx -> {
 			var builder = this.requestBuilder.copy()
 				.uri(requestUri)
 				.header("Content-Type", "application/json")
 				.header(MCP_PROTOCOL_VERSION_HEADER_NAME, MCP_PROTOCOL_VERSION)
 				.POST(HttpRequest.BodyPublishers.ofString(body));
-			return Mono.from(this.httpRequestCustomizer.customize(builder, "POST", requestUri, body));
+			var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+			return Mono.from(this.httpRequestCustomizer.customize(builder, "POST", requestUri, body, transportContext));
 		}).flatMap(customizedBuilder -> {
 			var request = customizedBuilder.build();
 			return Mono.fromFuture(httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString()));
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index a3815d0cf..4b1ff0d8b 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -25,9 +25,10 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
-import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
 import io.modelcontextprotocol.spec.HttpHeaders;
@@ -115,7 +116,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private final boolean resumableStreams;
 
-	private final McpAsyncHttpRequestCustomizer httpRequestCustomizer;
+	private final McpAsyncHttpClientRequestCustomizer httpRequestCustomizer;
 
 	private final AtomicReference activeSession = new AtomicReference<>();
 
@@ -125,7 +126,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private HttpClientStreamableHttpTransport(ObjectMapper objectMapper, HttpClient httpClient,
 			HttpRequest.Builder requestBuilder, String baseUri, String endpoint, boolean resumableStreams,
-			boolean openConnectionOnStartup, McpAsyncHttpRequestCustomizer httpRequestCustomizer) {
+			boolean openConnectionOnStartup, McpAsyncHttpClientRequestCustomizer httpRequestCustomizer) {
 		this.objectMapper = objectMapper;
 		this.httpClient = httpClient;
 		this.requestBuilder = requestBuilder;
@@ -170,14 +171,15 @@ private DefaultMcpTransportSession createTransportSession() {
 	private Publisher createDelete(String sessionId) {
 
 		var uri = Utils.resolveUri(this.baseUri, this.endpoint);
-		return Mono.defer(() -> {
+		return Mono.deferContextual(ctx -> {
 			var builder = this.requestBuilder.copy()
 				.uri(uri)
 				.header("Cache-Control", "no-cache")
 				.header(HttpHeaders.MCP_SESSION_ID, sessionId)
 				.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 				.DELETE();
-			return Mono.from(this.httpRequestCustomizer.customize(builder, "DELETE", uri, null));
+			var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+			return Mono.from(this.httpRequestCustomizer.customize(builder, "DELETE", uri, null, transportContext));
 		}).flatMap(requestBuilder -> {
 			var request = requestBuilder.build();
 			return Mono.fromFuture(() -> this.httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString()));
@@ -230,7 +232,7 @@ private Mono reconnect(McpTransportStream stream) {
 			final McpTransportSession transportSession = this.activeSession.get();
 			var uri = Utils.resolveUri(this.baseUri, this.endpoint);
 
-			Disposable connection = Mono.defer(() -> {
+			Disposable connection = Mono.deferContextual(connectionCtx -> {
 				HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
 
 				if (transportSession != null && transportSession.sessionId().isPresent()) {
@@ -247,7 +249,8 @@ private Mono reconnect(McpTransportStream 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 = connectionCtx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null, transportContext));
 			})
 				.flatMapMany(
 						requestBuilder -> Flux.create(
@@ -407,7 +410,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 			var uri = Utils.resolveUri(this.baseUri, this.endpoint);
 			String jsonBody = this.toString(sentMessage);
 
-			Disposable connection = Mono.defer(() -> {
+			Disposable connection = Mono.deferContextual(ctx -> {
 				HttpRequest.Builder requestBuilder = this.requestBuilder.copy();
 
 				if (transportSession != null && transportSession.sessionId().isPresent()) {
@@ -421,7 +424,9 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 					.header("Cache-Control", "no-cache")
 					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
-				return Mono.from(this.httpRequestCustomizer.customize(builder, "POST", uri, jsonBody));
+				var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+				return Mono
+					.from(this.httpRequestCustomizer.customize(builder, "POST", uri, jsonBody, transportContext));
 			}).flatMapMany(requestBuilder -> Flux.create(responseEventSink -> {
 
 				// Create the async request with proper body subscriber selection
@@ -600,7 +605,7 @@ public static class Builder {
 
 		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder();
 
-		private McpAsyncHttpRequestCustomizer httpRequestCustomizer = McpAsyncHttpRequestCustomizer.NOOP;
+		private McpAsyncHttpClientRequestCustomizer httpRequestCustomizer = McpAsyncHttpClientRequestCustomizer.NOOP;
 
 		private Duration connectTimeout = Duration.ofSeconds(10);
 
@@ -711,16 +716,17 @@ public Builder openConnectionOnStartup(boolean openConnectionOnStartup) {
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}.
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer)}.
 		 * 

-		 * Do NOT use a blocking {@link McpSyncHttpRequestCustomizer} in a non-blocking
-		 * context. Use {@link #asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer)}
+		 * Do NOT use a blocking {@link McpSyncHttpClientRequestCustomizer} in a
+		 * non-blocking context. Use
+		 * {@link #asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer)}
 		 * instead.
 		 * @param syncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder httpRequestCustomizer(McpSyncHttpRequestCustomizer syncHttpRequestCustomizer) {
-			this.httpRequestCustomizer = McpAsyncHttpRequestCustomizer.fromSync(syncHttpRequestCustomizer);
+		public Builder httpRequestCustomizer(McpSyncHttpClientRequestCustomizer syncHttpRequestCustomizer) {
+			this.httpRequestCustomizer = McpAsyncHttpClientRequestCustomizer.fromSync(syncHttpRequestCustomizer);
 			return this;
 		}
 
@@ -729,13 +735,13 @@ public Builder httpRequestCustomizer(McpSyncHttpRequestCustomizer syncHttpReques
 		 * executing them.
 		 * 

 		 * This overrides the customizer from
-		 * {@link #httpRequestCustomizer(McpSyncHttpRequestCustomizer)}.
+		 * {@link #httpRequestCustomizer(McpSyncHttpClientRequestCustomizer)}.
 		 * 

 		 * Do NOT use a blocking implementation in a non-blocking context.
 		 * @param asyncHttpRequestCustomizer the request customizer
 		 * @return this builder
 		 */
-		public Builder asyncHttpRequestCustomizer(McpAsyncHttpRequestCustomizer asyncHttpRequestCustomizer) {
+		public Builder asyncHttpRequestCustomizer(McpAsyncHttpClientRequestCustomizer asyncHttpRequestCustomizer) {
 			this.httpRequestCustomizer = asyncHttpRequestCustomizer;
 			return this;
 		}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java
similarity index 58%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizer.java
rename to mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java
index 22ba6a265..2492efe18 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java
@@ -3,34 +3,38 @@
  */
 package io.modelcontextprotocol.client.transport.customizer;
 
-import io.modelcontextprotocol.util.Assert;
 import java.net.URI;
 import java.net.http.HttpRequest;
 import java.util.List;
+
 import org.reactivestreams.Publisher;
+
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.util.Assert;
+
 import reactor.core.publisher.Mono;
 
 /**
- * Composable {@link McpAsyncHttpRequestCustomizer} that applies multiple customizers, in
- * order.
+ * Composable {@link McpAsyncHttpClientRequestCustomizer} that applies multiple
+ * customizers, in order.
  *
  * @author Daniel Garnier-Moiroux
  */
-public class DelegatingMcpAsyncHttpRequestCustomizer implements McpAsyncHttpRequestCustomizer {
+public class DelegatingMcpAsyncHttpClientRequestCustomizer implements McpAsyncHttpClientRequestCustomizer {
 
-	private final List customizers;
+	private final List customizers;
 
-	public DelegatingMcpAsyncHttpRequestCustomizer(List customizers) {
+	public DelegatingMcpAsyncHttpClientRequestCustomizer(List customizers) {
 		Assert.notNull(customizers, "Customizers must not be null");
 		this.customizers = customizers;
 	}
 
 	@Override
 	public Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
-			String body) {
+			String body, McpTransportContext context) {
 		var result = Mono.just(builder);
 		for (var customizer : this.customizers) {
-			result = result.flatMap(b -> Mono.from(customizer.customize(b, method, endpoint, body)));
+			result = result.flatMap(b -> Mono.from(customizer.customize(b, method, endpoint, body, context)));
 		}
 		return result;
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java
new file mode 100644
index 000000000..e627e7e69
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport.customizer;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.util.List;
+
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.util.Assert;
+
+/**
+ * Composable {@link McpSyncHttpClientRequestCustomizer} that applies multiple
+ * customizers, in order.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+public class DelegatingMcpSyncHttpClientRequestCustomizer implements McpSyncHttpClientRequestCustomizer {
+
+	private final List delegates;
+
+	public DelegatingMcpSyncHttpClientRequestCustomizer(List customizers) {
+		Assert.notNull(customizers, "Customizers must not be null");
+		this.delegates = customizers;
+	}
+
+	@Override
+	public void customize(HttpRequest.Builder builder, String method, URI endpoint, String body,
+			McpTransportContext context) {
+		this.delegates.forEach(delegate -> delegate.customize(builder, method, endpoint, body, context));
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java
deleted file mode 100644
index 65649d916..000000000
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizer.java
+++ /dev/null
@@ -1,32 +0,0 @@
-/*
- * Copyright 2024-2025 the original author or authors.
- */
-
-package io.modelcontextprotocol.client.transport.customizer;
-
-import io.modelcontextprotocol.util.Assert;
-import java.net.URI;
-import java.net.http.HttpRequest;
-import java.util.List;
-
-/**
- * Composable {@link McpSyncHttpRequestCustomizer} that applies multiple customizers, in
- * order.
- *
- * @author Daniel Garnier-Moiroux
- */
-public class DelegatingMcpSyncHttpRequestCustomizer implements McpSyncHttpRequestCustomizer {
-
-	private final List delegates;
-
-	public DelegatingMcpSyncHttpRequestCustomizer(List customizers) {
-		Assert.notNull(customizers, "Customizers must not be null");
-		this.delegates = customizers;
-	}
-
-	@Override
-	public void customize(HttpRequest.Builder builder, String method, URI endpoint, String body) {
-		this.delegates.forEach(delegate -> delegate.customize(builder, method, endpoint, body));
-	}
-
-}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java
similarity index 65%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpRequestCustomizer.java
rename to mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java
index 2f685c350..756b39c35 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpRequestCustomizer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java
@@ -6,11 +6,14 @@
 
 import java.net.URI;
 import java.net.http.HttpRequest;
+
 import org.reactivestreams.Publisher;
 import reactor.core.publisher.Mono;
 import reactor.core.scheduler.Schedulers;
 import reactor.util.annotation.Nullable;
 
+import io.modelcontextprotocol.common.McpTransportContext;
+
 /**
  * Customize {@link HttpRequest.Builder} before executing the request, in either SSE or
  * Streamable HTTP transport.
@@ -19,12 +22,12 @@
  *
  * @author Daniel Garnier-Moiroux
  */
-public interface McpAsyncHttpRequestCustomizer {
+public interface McpAsyncHttpClientRequestCustomizer {
 
 	Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
-			@Nullable String body);
+			@Nullable String body, McpTransportContext context);
 
-	McpAsyncHttpRequestCustomizer NOOP = new Noop();
+	McpAsyncHttpClientRequestCustomizer NOOP = new Noop();
 
 	/**
 	 * Wrap a sync implementation in an async wrapper.
@@ -32,18 +35,18 @@ Publisher customize(HttpRequest.Builder builder, String met
 	 * Do NOT wrap a blocking implementation for use in a non-blocking context. For a
 	 * blocking implementation, consider using {@link Schedulers#boundedElastic()}.
 	 */
-	static McpAsyncHttpRequestCustomizer fromSync(McpSyncHttpRequestCustomizer customizer) {
-		return (builder, method, uri, body) -> Mono.fromSupplier(() -> {
-			customizer.customize(builder, method, uri, body);
+	static McpAsyncHttpClientRequestCustomizer fromSync(McpSyncHttpClientRequestCustomizer customizer) {
+		return (builder, method, uri, body, context) -> Mono.fromSupplier(() -> {
+			customizer.customize(builder, method, uri, body, context);
 			return builder;
 		});
 	}
 
-	class Noop implements McpAsyncHttpRequestCustomizer {
+	class Noop implements McpAsyncHttpClientRequestCustomizer {
 
 		@Override
 		public Publisher customize(HttpRequest.Builder builder, String method, URI endpoint,
-				String body) {
+				String body, McpTransportContext context) {
 			return Mono.just(builder);
 		}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java
new file mode 100644
index 000000000..e22e3aa62
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client.transport.customizer;
+
+import java.net.URI;
+import java.net.http.HttpRequest;
+
+import reactor.util.annotation.Nullable;
+
+import io.modelcontextprotocol.client.McpClient.SyncSpec;
+import io.modelcontextprotocol.common.McpTransportContext;
+
+/**
+ * Customize {@link HttpRequest.Builder} before executing the request, either in SSE or
+ * 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 McpSyncHttpClientRequestCustomizer {
+
+	void customize(HttpRequest.Builder builder, String method, URI endpoint, @Nullable String body,
+			McpTransportContext context);
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java
deleted file mode 100644
index 8d2c4a698..000000000
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpRequestCustomizer.java
+++ /dev/null
@@ -1,21 +0,0 @@
-/*
- * Copyright 2024-2025 the original author or authors.
- */
-
-package io.modelcontextprotocol.client.transport.customizer;
-
-import java.net.URI;
-import java.net.http.HttpRequest;
-import reactor.util.annotation.Nullable;
-
-/**
- * Customize {@link HttpRequest.Builder} before executing the request, either in SSE or
- * Streamable HTTP transport.
- *
- * @author Daniel Garnier-Moiroux
- */
-public interface McpSyncHttpRequestCustomizer {
-
-	void customize(HttpRequest.Builder builder, String method, URI endpoint, @Nullable String body);
-
-}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java
new file mode 100644
index 000000000..cde637b15
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.common;
+
+import java.util.Map;
+
+import io.modelcontextprotocol.util.Assert;
+
+/**
+ * Default implementation for {@link McpTransportContext} which uses a map as storage.
+ *
+ * @author Dariusz Jędrzejczyk
+ * @author Daniel Garnier-Moiroux
+ */
+class DefaultMcpTransportContext implements McpTransportContext {
+
+	private final Map metadata;
+
+	DefaultMcpTransportContext(Map metadata) {
+		Assert.notNull(metadata, "The metadata cannot be null");
+		this.metadata = metadata;
+	}
+
+	@Override
+	public Object get(String key) {
+		return this.metadata.get(key);
+	}
+
+	@Override
+	public boolean equals(Object o) {
+		if (o == null || getClass() != o.getClass())
+			return false;
+
+		DefaultMcpTransportContext that = (DefaultMcpTransportContext) o;
+		return this.metadata.equals(that.metadata);
+	}
+
+	@Override
+	public int hashCode() {
+		return this.metadata.hashCode();
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java
similarity index 68%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
rename to mcp/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java
index 1cd540f72..46a2ccf84 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContext.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java
@@ -2,9 +2,10 @@
  * Copyright 2024-2025 the original author or authors.
  */
 
-package io.modelcontextprotocol.server;
+package io.modelcontextprotocol.common;
 
 import java.util.Collections;
+import java.util.Map;
 
 /**
  * Context associated with the transport layer. It allows to add transport-level metadata
@@ -26,6 +27,15 @@ public interface McpTransportContext {
 	@SuppressWarnings("unchecked")
 	McpTransportContext EMPTY = new DefaultMcpTransportContext(Collections.EMPTY_MAP);
 
+	/**
+	 * Create an unmodifiable context containing the given metadata.
+	 * @param metadata the transport metadata
+	 * @return the context containing the metadata
+	 */
+	static McpTransportContext create(Map metadata) {
+		return new DefaultMcpTransportContext(metadata);
+	}
+
 	/**
 	 * Extract a value from the context.
 	 * @param key the key under the data is expected
@@ -33,18 +43,4 @@ public interface McpTransportContext {
 	 */
 	Object get(String key);
 
-	/**
-	 * Inserts a value for a given key.
-	 * @param key a String representing the key
-	 * @param value the value to store
-	 */
-	void put(String key, Object value);
-
-	/**
-	 * Copies the contents of the context to allow further modifications without affecting
-	 * the initial object.
-	 * @return a new instance with the underlying storage copied.
-	 */
-	McpTransportContext copy();
-
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
index 2df3514b6..d1b55f594 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import org.slf4j.Logger;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java b/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
deleted file mode 100644
index 9e18e189d..000000000
--- a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpTransportContext.java
+++ /dev/null
@@ -1,49 +0,0 @@
-/*
- * Copyright 2024-2025 the original author or authors.
- */
-
-package io.modelcontextprotocol.server;
-
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-
-/**
- * Default implementation for {@link McpTransportContext} which uses a Thread-safe map.
- * Objects of this kind are mutable.
- *
- * @author Dariusz Jędrzejczyk
- */
-public class DefaultMcpTransportContext implements McpTransportContext {
-
-	private final Map storage;
-
-	/**
-	 * Create an empty instance.
-	 */
-	public DefaultMcpTransportContext() {
-		this.storage = new ConcurrentHashMap<>();
-	}
-
-	DefaultMcpTransportContext(Map storage) {
-		this.storage = storage;
-	}
-
-	@Override
-	public Object get(String key) {
-		return this.storage.get(key);
-	}
-
-	@Override
-	public void put(String key, Object value) {
-		this.storage.put(key, value);
-	}
-
-	/**
-	 * Allows copying the contents.
-	 * @return new instance with the copy of the underlying map
-	 */
-	public McpTransportContext copy() {
-		return new DefaultMcpTransportContext(new ConcurrentHashMap<>(this.storage));
-	}
-
-}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
index 61d60bacc..1f0aebf02 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import java.util.ArrayList;
 import java.util.Collections;
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
index f5dfffffb..76a0de76b 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Arrays;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 41e0e9588..451771295 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -6,6 +6,7 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
index 6db79a62c..a2fabb283 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import reactor.core.publisher.Mono;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
index e5c9e7c09..37cd3c096 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import reactor.core.publisher.Mono;
 
 /**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
index 60c1dbb65..df44d50c4 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
 import io.modelcontextprotocol.util.Assert;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
index 7c4e23cfc..cbae58bfd 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpSchema;
 import reactor.core.publisher.Mono;
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
index 5f22df5e9..0b9115b79 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
index 97fcecf0d..ea9f05a4f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
+
 /**
  * The contract for extracting metadata from a generic transport request of type
  * {@link T}.
@@ -15,14 +17,11 @@
 public interface McpTransportContextExtractor {
 
 	/**
-	 * Given an empty context, provides the means to fill it with transport-specific
-	 * metadata extracted from the request.
+	 * Extract transport-specific metadata from the request into an McpTransportContext.
 	 * @param request the generic representation for the request in the context of a
 	 * specific transport implementation
-	 * @param transportContext the mutable context which can be filled in with metadata
-	 * @return the context filled in with metadata. It can be the same instance as
-	 * provided or a new one.
+	 * @return the context containing the metadata
 	 */
-	McpTransportContext extract(T request, McpTransportContext transportContext);
+	McpTransportContext extract(T request);
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index 582120e3f..bbc1edf24 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -16,8 +16,7 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
-import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -149,7 +148,7 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String m
 	@Deprecated
 	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null, (serverRequest, context) -> context);
+		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null, (serverRequest) -> McpTransportContext.EMPTY);
 	}
 
 	/**
@@ -169,7 +168,7 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String b
 	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval) {
 		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
-				(serverRequest, context) -> context);
+				(serverRequest) -> McpTransportContext.EMPTY);
 	}
 
 	/**
@@ -371,8 +370,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 				body.append(line);
 			}
 
-			final McpTransportContext transportContext = this.contextExtractor.extract(request,
-					new DefaultMcpTransportContext());
+			final McpTransportContext transportContext = this.contextExtractor.extract(request);
 			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body.toString());
 
 			// Process the message through the session's handle method
@@ -569,7 +567,8 @@ public static class Builder {
 
 		private String sseEndpoint = DEFAULT_SSE_ENDPOINT;
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		private Duration keepAliveInterval;
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
index 25b003564..9a8f6cbb9 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
@@ -13,9 +13,8 @@
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
-import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -123,7 +122,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			return;
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		String accept = request.getHeader(ACCEPT);
 		if (accept == null || !(accept.contains(APPLICATION_JSON) && accept.contains(TEXT_EVENT_STREAM))) {
@@ -241,7 +240,8 @@ public static class Builder {
 
 		private String mcpEndpoint = "/mcp";
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		private Builder() {
 			// used by a static method
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
index 8b95ec607..3cb8d7b15 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
@@ -19,8 +19,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.server.DefaultMcpTransportContext;
-import io.modelcontextprotocol.server.McpTransportContext;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpError;
@@ -274,7 +273,7 @@ protected void doGet(HttpServletRequest request, HttpServletResponse response)
 
 		logger.debug("Handling GET request for session: {}", sessionId);
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		try {
 			response.setContentType(TEXT_EVENT_STREAM);
@@ -383,7 +382,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			badRequestErrors.add("application/json required in Accept header");
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		try {
 			BufferedReader reader = request.getReader();
@@ -541,7 +540,7 @@ protected void doDelete(HttpServletRequest request, HttpServletResponse response
 			return;
 		}
 
-		McpTransportContext transportContext = this.contextExtractor.extract(request, new DefaultMcpTransportContext());
+		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		if (request.getHeader(HttpHeaders.MCP_SESSION_ID) == null) {
 			this.responseError(response, HttpServletResponse.SC_BAD_REQUEST,
@@ -769,7 +768,8 @@ public static class Builder {
 
 		private boolean disallowDelete = false;
 
-		private McpTransportContextExtractor contextExtractor = (serverRequest, context) -> context;
+		private McpTransportContextExtractor contextExtractor = (
+				serverRequest) -> McpTransportContext.EMPTY;
 
 		private Duration keepAliveInterval;
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index e562ca012..e6a0c8b32 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -12,11 +12,11 @@
 import java.util.concurrent.atomic.AtomicReference;
 
 import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
 import io.modelcontextprotocol.server.McpInitRequestHandler;
 import io.modelcontextprotocol.server.McpNotificationHandler;
 import io.modelcontextprotocol.server.McpRequestHandler;
-import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
index ef7967c1e..af29ce0ad 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -17,10 +17,10 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
 import io.modelcontextprotocol.server.McpNotificationHandler;
 import io.modelcontextprotocol.server.McpRequestHandler;
-import io.modelcontextprotocol.server.McpTransportContext;
 import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
index 7f00de60e..6f3b58e3d 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
@@ -4,13 +4,26 @@
 
 package io.modelcontextprotocol.client;
 
+import java.net.URI;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
 
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpClientTransport;
 
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
 @Timeout(15)
 public class HttpClientStreamableHttpSyncClientTests extends AbstractMcpSyncClientTests {
 
@@ -24,9 +37,11 @@ public class HttpClientStreamableHttpSyncClientTests extends AbstractMcpSyncClie
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
 
+	private final McpSyncHttpClientRequestCustomizer requestCustomizer = mock(McpSyncHttpClientRequestCustomizer.class);
+
 	@Override
 	protected McpClientTransport createMcpTransport() {
-		return HttpClientStreamableHttpTransport.builder(host).build();
+		return HttpClientStreamableHttpTransport.builder(host).httpRequestCustomizer(requestCustomizer).build();
 	}
 
 	@Override
@@ -41,4 +56,17 @@ public void onClose() {
 		container.stop();
 	}
 
+	@Test
+	void customizesRequests() {
+		var mcpTransportContext = McpTransportContext.create(Map.of("some-key", "some-value"));
+		withClient(createMcpTransport(), syncSpec -> syncSpec.transportContextProvider(() -> mcpTransportContext),
+				mcpSyncClient -> {
+					mcpSyncClient.initialize();
+
+					verify(requestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(URI.create(host + "/mcp")),
+							eq("{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"),
+							eq(mcpTransportContext));
+				});
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
index 8646c1b4c..4091d7a5e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
@@ -4,12 +4,27 @@
 
 package io.modelcontextprotocol.client;
 
-import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
-import io.modelcontextprotocol.spec.McpClientTransport;
+import java.net.URI;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
 
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.spec.McpClientTransport;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+
 /**
  * Tests for the {@link McpSyncClient} with {@link HttpClientSseClientTransport}.
  *
@@ -28,9 +43,11 @@ class HttpSseMcpSyncClientTests extends AbstractMcpSyncClientTests {
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
 
+	private final McpSyncHttpClientRequestCustomizer requestCustomizer = mock(McpSyncHttpClientRequestCustomizer.class);
+
 	@Override
 	protected McpClientTransport createMcpTransport() {
-		return HttpClientSseClientTransport.builder(host).build();
+		return HttpClientSseClientTransport.builder(host).httpRequestCustomizer(requestCustomizer).build();
 	}
 
 	@Override
@@ -45,4 +62,16 @@ protected void onClose() {
 		container.stop();
 	}
 
+	@Test
+	void customizesRequests() {
+		var mcpTransportContext = McpTransportContext.create(Map.of("some-key", "some-value"));
+		withClient(createMcpTransport(), syncSpec -> syncSpec.transportContextProvider(() -> mcpTransportContext),
+				mcpSyncClient -> {
+					mcpSyncClient.initialize();
+
+					verify(requestCustomizer, atLeastOnce()).customize(any(), eq("GET"), eq(URI.create(host + "/sse")),
+							isNull(), eq(mcpTransportContext));
+				});
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
index f5a5ecb12..257d65f06 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
@@ -15,10 +15,13 @@
 import java.util.function.Function;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
-import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
-import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
+
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCRequest;
+
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeAll;
@@ -64,6 +67,8 @@ class HttpClientSseClientTransportTests {
 
 	private TestHttpClientSseClientTransport transport;
 
+	private final McpTransportContext context = McpTransportContext.create(Map.of("some-key", "some-value"));
+
 	// Test class to access protected methods
 	static class TestHttpClientSseClientTransport extends HttpClientSseClientTransport {
 
@@ -74,7 +79,7 @@ static class TestHttpClientSseClientTransport extends HttpClientSseClientTranspo
 		public TestHttpClientSseClientTransport(final String baseUri) {
 			super(HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build(),
 					HttpRequest.newBuilder().header("Content-Type", "application/json"), baseUri, "/sse",
-					new ObjectMapper(), McpAsyncHttpRequestCustomizer.NOOP);
+					new ObjectMapper(), McpAsyncHttpClientRequestCustomizer.NOOP);
 		}
 
 		public int getInboundMessageCount() {
@@ -391,7 +396,7 @@ void testChainedCustomizations() {
 
 	@Test
 	void testRequestCustomizer() {
-		var mockCustomizer = mock(McpSyncHttpRequestCustomizer.class);
+		var mockCustomizer = mock(McpSyncHttpClientRequestCustomizer.class);
 
 		// Create a transport with the customizer
 		var customizedTransport = HttpClientSseClientTransport.builder(host)
@@ -399,11 +404,14 @@ void testRequestCustomizer() {
 			.build();
 
 		// Connect
-		StepVerifier.create(customizedTransport.connect(Function.identity())).verifyComplete();
+		StepVerifier
+			.create(customizedTransport.connect(Function.identity())
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+			.verifyComplete();
 
 		// Verify the customizer was called
 		verify(mockCustomizer).customize(any(), eq("GET"),
-				eq(UriComponentsBuilder.fromUriString(host).path("/sse").build().toUri()), isNull());
+				eq(UriComponentsBuilder.fromUriString(host).path("/sse").build().toUri()), isNull(), eq(context));
 		clearInvocations(mockCustomizer);
 
 		// Send test message
@@ -411,12 +419,16 @@ void testRequestCustomizer() {
 				Map.of("key", "value"));
 
 		// Subscribe to messages and verify
-		StepVerifier.create(customizedTransport.sendMessage(testMessage)).verifyComplete();
+		StepVerifier
+			.create(customizedTransport.sendMessage(testMessage)
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+			.verifyComplete();
 
 		// Verify the customizer was called
 		var uriArgumentCaptor = ArgumentCaptor.forClass(URI.class);
 		verify(mockCustomizer).customize(any(), eq("POST"), uriArgumentCaptor.capture(), eq(
-				"{\"jsonrpc\":\"2.0\",\"method\":\"test-method\",\"id\":\"test-id\",\"params\":{\"key\":\"value\"}}"));
+				"{\"jsonrpc\":\"2.0\",\"method\":\"test-method\",\"id\":\"test-id\",\"params\":{\"key\":\"value\"}}"),
+				eq(context));
 		assertThat(uriArgumentCaptor.getValue().toString()).startsWith(host + "/message?sessionId=");
 
 		// Clean up
@@ -425,8 +437,8 @@ void testRequestCustomizer() {
 
 	@Test
 	void testAsyncRequestCustomizer() {
-		var mockCustomizer = mock(McpAsyncHttpRequestCustomizer.class);
-		when(mockCustomizer.customize(any(), any(), any(), any()))
+		var mockCustomizer = mock(McpAsyncHttpClientRequestCustomizer.class);
+		when(mockCustomizer.customize(any(), any(), any(), any(), any()))
 			.thenAnswer(invocation -> Mono.just(invocation.getArguments()[0]));
 
 		// Create a transport with the customizer
@@ -435,11 +447,14 @@ void testAsyncRequestCustomizer() {
 			.build();
 
 		// Connect
-		StepVerifier.create(customizedTransport.connect(Function.identity())).verifyComplete();
+		StepVerifier
+			.create(customizedTransport.connect(Function.identity())
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+			.verifyComplete();
 
 		// Verify the customizer was called
 		verify(mockCustomizer).customize(any(), eq("GET"),
-				eq(UriComponentsBuilder.fromUriString(host).path("/sse").build().toUri()), isNull());
+				eq(UriComponentsBuilder.fromUriString(host).path("/sse").build().toUri()), isNull(), eq(context));
 		clearInvocations(mockCustomizer);
 
 		// Send test message
@@ -447,12 +462,16 @@ void testAsyncRequestCustomizer() {
 				Map.of("key", "value"));
 
 		// Subscribe to messages and verify
-		StepVerifier.create(customizedTransport.sendMessage(testMessage)).verifyComplete();
+		StepVerifier
+			.create(customizedTransport.sendMessage(testMessage)
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+			.verifyComplete();
 
 		// Verify the customizer was called
 		var uriArgumentCaptor = ArgumentCaptor.forClass(URI.class);
 		verify(mockCustomizer).customize(any(), eq("POST"), uriArgumentCaptor.capture(), eq(
-				"{\"jsonrpc\":\"2.0\",\"method\":\"test-method\",\"id\":\"test-id\",\"params\":{\"key\":\"value\"}}"));
+				"{\"jsonrpc\":\"2.0\",\"method\":\"test-method\",\"id\":\"test-id\",\"params\":{\"key\":\"value\"}}"),
+				eq(context));
 		assertThat(uriArgumentCaptor.getValue().toString()).startsWith(host + "/message?sessionId=");
 
 		// Clean up
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
index e7d048ffe..250c7aa50 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
@@ -22,7 +22,7 @@
 
 import com.sun.net.httpserver.HttpServer;
 
-import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.ProtocolVersions;
@@ -71,7 +71,7 @@ static void stopContainer() {
 	void testNotificationInitialized() throws URISyntaxException {
 
 		var uri = new URI(host + "/mcp");
-		var mockRequestCustomizer = mock(McpSyncHttpRequestCustomizer.class);
+		var mockRequestCustomizer = mock(McpSyncHttpClientRequestCustomizer.class);
 		var transport = HttpClientStreamableHttpTransport.builder(host)
 			.httpRequestCustomizer(mockRequestCustomizer)
 			.build();
@@ -86,7 +86,8 @@ void testNotificationInitialized() throws URISyntaxException {
 
 		// Verify the customizer was called
 		verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-				"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
+				"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+				any());
 
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index f08518c93..670e6c7e6 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -4,11 +4,13 @@
 
 package io.modelcontextprotocol.client.transport;
 
-import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpRequestCustomizer;
-import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpSchema;
 import java.net.URI;
 import java.net.URISyntaxException;
+import java.util.Map;
 import java.util.function.Consumer;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
@@ -18,6 +20,7 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.atLeastOnce;
@@ -34,6 +37,9 @@ class HttpClientStreamableHttpTransportTest {
 
 	static String host = "http://localhost:3001";
 
+	private McpTransportContext context = McpTransportContext
+		.create(Map.of("test-transport-context-key", "some-value"));
+
 	@SuppressWarnings("resource")
 	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js streamableHttp")
@@ -65,7 +71,7 @@ void withTransport(HttpClientStreamableHttpTransport transport, Consumer ctx.put(McpTransportContext.KEY, context)))
+				.verifyComplete();
 
 			// Verify the customizer was called
 			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+					eq(context));
 		});
 	}
 
 	@Test
 	void testAsyncRequestCustomizer() throws URISyntaxException {
 		var uri = new URI(host + "/mcp");
-		var mockRequestCustomizer = mock(McpAsyncHttpRequestCustomizer.class);
-		when(mockRequestCustomizer.customize(any(), any(), any(), any()))
+		var mockRequestCustomizer = mock(McpAsyncHttpClientRequestCustomizer.class);
+		when(mockRequestCustomizer.customize(any(), any(), any(), any(), any()))
 			.thenAnswer(invocation -> Mono.just(invocation.getArguments()[0]));
 
 		var transport = HttpClientStreamableHttpTransport.builder(host)
@@ -106,11 +115,14 @@ void testAsyncRequestCustomizer() throws URISyntaxException {
 			var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 					"test-id", initializeRequest);
 
-			StepVerifier.create(t.sendMessage(testMessage)).verifyComplete();
+			StepVerifier
+				.create(t.sendMessage(testMessage).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, context)))
+				.verifyComplete();
 
 			// Verify the customizer was called
 			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"));
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+					eq(context));
 		});
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizerTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java
similarity index 57%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizerTest.java
rename to mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java
index f136cd65e..a04787aa3 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpRequestCustomizerTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java
@@ -11,6 +11,8 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import io.modelcontextprotocol.common.McpTransportContext;
+
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
@@ -18,11 +20,11 @@
 import static org.mockito.Mockito.when;
 
 /**
- * Tests for {@link DelegatingMcpAsyncHttpRequestCustomizer}.
+ * Tests for {@link DelegatingMcpAsyncHttpClientRequestCustomizer}.
  *
  * @author Daniel Garnier-Moiroux
  */
-class DelegatingMcpAsyncHttpRequestCustomizerTest {
+class DelegatingMcpAsyncHttpClientRequestCustomizerTest {
 
 	private static final URI TEST_URI = URI.create("https://example.com");
 
@@ -30,26 +32,29 @@ class DelegatingMcpAsyncHttpRequestCustomizerTest {
 
 	@Test
 	void delegates() {
-		var mockCustomizer = mock(McpAsyncHttpRequestCustomizer.class);
-		when(mockCustomizer.customize(any(), any(), any(), any()))
+		var mockCustomizer = mock(McpAsyncHttpClientRequestCustomizer.class);
+		when(mockCustomizer.customize(any(), any(), any(), any(), any()))
 			.thenAnswer(invocation -> Mono.just(invocation.getArguments()[0]));
-		var customizer = new DelegatingMcpAsyncHttpRequestCustomizer(List.of(mockCustomizer));
+		var customizer = new DelegatingMcpAsyncHttpClientRequestCustomizer(List.of(mockCustomizer));
 
-		StepVerifier.create(customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}"))
+		var context = McpTransportContext.EMPTY;
+		StepVerifier
+			.create(customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}", context))
 			.expectNext(TEST_BUILDER)
 			.verifyComplete();
 
-		verify(mockCustomizer).customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}");
+		verify(mockCustomizer).customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}", context);
 	}
 
 	@Test
 	void delegatesInOrder() {
-		var customizer = new DelegatingMcpAsyncHttpRequestCustomizer(
-				List.of((builder, method, uri, body) -> Mono.just(builder.copy().header("x-test", "one")),
-						(builder, method, uri, body) -> Mono.just(builder.copy().header("x-test", "two"))));
+		var customizer = new DelegatingMcpAsyncHttpClientRequestCustomizer(
+				List.of((builder, method, uri, body, ctx) -> Mono.just(builder.copy().header("x-test", "one")),
+						(builder, method, uri, body, ctx) -> Mono.just(builder.copy().header("x-test", "two"))));
 
 		var headers = Mono
-			.from(customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}"))
+			.from(customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}",
+					McpTransportContext.EMPTY))
 			.map(HttpRequest.Builder::build)
 			.map(HttpRequest::headers)
 			.flatMapIterable(h -> h.allValues("x-test"));
@@ -59,7 +64,7 @@ void delegatesInOrder() {
 
 	@Test
 	void constructorRequiresNonNull() {
-		assertThatThrownBy(() -> new DelegatingMcpAsyncHttpRequestCustomizer(null))
+		assertThatThrownBy(() -> new DelegatingMcpAsyncHttpClientRequestCustomizer(null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Customizers must not be null");
 	}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizerTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java
similarity index 55%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizerTest.java
rename to mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java
index 427472912..6c51a3d12 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpRequestCustomizerTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java
@@ -10,16 +10,18 @@
 import org.junit.jupiter.api.Test;
 import org.mockito.Mockito;
 
+import io.modelcontextprotocol.common.McpTransportContext;
+
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.Mockito.verify;
 
 /**
- * Tests for {@link DelegatingMcpSyncHttpRequestCustomizer}.
+ * Tests for {@link DelegatingMcpSyncHttpClientRequestCustomizer}.
  *
  * @author Daniel Garnier-Moiroux
  */
-class DelegatingMcpSyncHttpRequestCustomizerTest {
+class DelegatingMcpSyncHttpClientRequestCustomizerTest {
 
 	private static final URI TEST_URI = URI.create("https://example.com");
 
@@ -27,22 +29,23 @@ class DelegatingMcpSyncHttpRequestCustomizerTest {
 
 	@Test
 	void delegates() {
-		var mockCustomizer = Mockito.mock(McpSyncHttpRequestCustomizer.class);
-		var customizer = new DelegatingMcpSyncHttpRequestCustomizer(List.of(mockCustomizer));
+		var mockCustomizer = Mockito.mock(McpSyncHttpClientRequestCustomizer.class);
+		var customizer = new DelegatingMcpSyncHttpClientRequestCustomizer(List.of(mockCustomizer));
 
-		customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}");
+		var context = McpTransportContext.EMPTY;
+		customizer.customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}", context);
 
-		verify(mockCustomizer).customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}");
+		verify(mockCustomizer).customize(TEST_BUILDER, "GET", TEST_URI, "{\"everybody\": \"needs somebody\"}", context);
 	}
 
 	@Test
 	void delegatesInOrder() {
 		var testHeaderName = "x-test";
-		var customizer = new DelegatingMcpSyncHttpRequestCustomizer(
-				List.of((builder, method, uri, body) -> builder.header(testHeaderName, "one"),
-						(builder, method, uri, body) -> builder.header(testHeaderName, "two")));
+		var customizer = new DelegatingMcpSyncHttpClientRequestCustomizer(
+				List.of((builder, method, uri, body, ctx) -> builder.header(testHeaderName, "one"),
+						(builder, method, uri, body, ctx) -> builder.header(testHeaderName, "two")));
 
-		customizer.customize(TEST_BUILDER, "GET", TEST_URI, "");
+		customizer.customize(TEST_BUILDER, "GET", TEST_URI, null, McpTransportContext.EMPTY);
 		var request = TEST_BUILDER.build();
 
 		assertThat(request.headers().allValues(testHeaderName)).containsExactly("one", "two");
@@ -50,7 +53,7 @@ void delegatesInOrder() {
 
 	@Test
 	void constructorRequiresNonNull() {
-		assertThatThrownBy(() -> new DelegatingMcpAsyncHttpRequestCustomizer(null))
+		assertThatThrownBy(() -> new DelegatingMcpAsyncHttpClientRequestCustomizer(null))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Customizers must not be null");
 	}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
new file mode 100644
index 000000000..8d75b8479
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
@@ -0,0 +1,241 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.common;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.McpClient.SyncSpec;
+import io.modelcontextprotocol.client.McpSyncClient;
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.McpSchema;
+import jakarta.servlet.Servlet;
+import jakarta.servlet.http.HttpServletRequest;
+import java.util.Map;
+import java.util.function.BiFunction;
+import java.util.function.Supplier;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Test both Client and Server {@link McpTransportContext} integration, in two steps.
+ * 

+ * First, the client calls a tool and writes data stored in a thread-local to an HTTP
+ * header using {@link SyncSpec#transportContextProvider(Supplier)} and
+ * {@link McpSyncHttpClientRequestCustomizer}.
+ * 

+ * Then the server reads the header with a {@link McpTransportContextExtractor} and
+ * returns the value as the result of the tool call.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+@Timeout(15)
+public class McpTransportContextIntegrationTests {
+
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
+	private Tomcat tomcat;
+
+	private static final ThreadLocal CLIENT_SIDE_HEADER_VALUE_HOLDER = new ThreadLocal<>();
+
+	private static final String HEADER_NAME = "x-test";
+
+	private final Supplier clientContextProvider = () -> {
+		var headerValue = CLIENT_SIDE_HEADER_VALUE_HOLDER.get();
+		return headerValue != null ? McpTransportContext.create(Map.of("client-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	private final McpSyncHttpClientRequestCustomizer clientRequestCustomizer = (builder, method, endpoint, body,
+			context) -> {
+		var headerValue = context.get("client-side-header-value");
+		if (headerValue != null) {
+			builder.header(HEADER_NAME, headerValue.toString());
+		}
+	};
+
+	private final McpTransportContextExtractor serverContextExtractor = (HttpServletRequest r) -> {
+		var headerValue = r.getHeader(HEADER_NAME);
+		return headerValue != null ? McpTransportContext.create(Map.of("server-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	private final BiFunction statelessHandler = (
+			transportContext,
+			request) -> new McpSchema.CallToolResult(transportContext.get("server-side-header-value").toString(), null);
+
+	private final BiFunction statefulHandler = (
+			exchange, request) -> statelessHandler.apply(exchange.transportContext(), request);
+
+	private final HttpServletStatelessServerTransport statelessServerTransport = HttpServletStatelessServerTransport
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final HttpServletStreamableServerTransportProvider streamableServerTransport = HttpServletStreamableServerTransportProvider
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final HttpServletSseServerTransportProvider sseServerTransport = HttpServletSseServerTransportProvider
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.messageEndpoint("/message")
+		.build();
+
+	private final McpSyncClient streamableClient = McpClient
+		.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+			.httpRequestCustomizer(clientRequestCustomizer)
+			.build())
+		.transportContextProvider(clientContextProvider)
+		.build();
+
+	private final McpSyncClient sseClient = McpClient
+		.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT)
+			.httpRequestCustomizer(clientRequestCustomizer)
+			.build())
+		.transportContextProvider(clientContextProvider)
+		.build();
+
+	private final McpSchema.Tool tool = McpSchema.Tool.builder()
+		.name("test-tool")
+		.description("return the value of the x-test header from call tool request")
+		.build();
+
+	@AfterEach
+	public void after() {
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.remove();
+		if (statelessServerTransport != null) {
+			statelessServerTransport.closeGracefully().block();
+		}
+		if (streamableServerTransport != null) {
+			streamableServerTransport.closeGracefully().block();
+		}
+		if (sseServerTransport != null) {
+			sseServerTransport.closeGracefully().block();
+		}
+		stopTomcat();
+	}
+
+	@Test
+	void statelessServer() {
+		startTomcat(statelessServerTransport);
+
+		var mcpServer = McpServer.sync(statelessServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpStatelessServerFeatures.SyncToolSpecification(tool, statelessHandler))
+			.build();
+
+		McpSchema.InitializeResult initResult = streamableClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = streamableClient
+			.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+
+		mcpServer.close();
+	}
+
+	@Test
+	void streamableServer() {
+		startTomcat(streamableServerTransport);
+
+		var mcpServer = McpServer.sync(streamableServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.SyncToolSpecification(tool, null, statefulHandler))
+			.build();
+
+		McpSchema.InitializeResult initResult = streamableClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = streamableClient
+			.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+
+		mcpServer.close();
+	}
+
+	@Test
+	void sseServer() {
+		startTomcat(sseServerTransport);
+
+		var mcpServer = McpServer.sync(sseServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.SyncToolSpecification(tool, null, statefulHandler))
+			.build();
+
+		McpSchema.InitializeResult initResult = sseClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = sseClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+
+		mcpServer.close();
+	}
+
+	private void startTomcat(Servlet transport) {
+		tomcat = TomcatTestUtil.createTomcatServer("", PORT, transport);
+		try {
+			tomcat.start();
+			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+	}
+
+	private void stopTomcat() {
+		if (tomcat != null) {
+			try {
+				tomcat.stop();
+				tomcat.destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index acaf0c8a9..f99edaf95 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -12,6 +12,7 @@
 import static org.awaitility.Awaitility.await;
 import static org.mockito.Mockito.mock;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
index 0f2991a9f..c893acf9a 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
@@ -6,7 +6,9 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import java.time.Duration;
+import java.util.Map;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
@@ -94,9 +96,7 @@ public void after() {
 	protected void prepareClients(int port, String mcpEndpoint) {
 	}
 
-	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
-		tc.put("important", "value");
-		return tc;
-	};
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r) -> McpTransportContext
+		.create(Map.of("important", "value"));
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index a8951e6dc..6a6f6f8b9 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -7,6 +7,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 import io.modelcontextprotocol.spec.HttpHeaders;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 2e9b4cbad..6899ba474 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -6,7 +6,9 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import java.time.Duration;
+import java.util.Map;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
@@ -92,9 +94,7 @@ public void after() {
 	protected void prepareClients(int port, String mcpEndpoint) {
 	}
 
-	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r, tc) -> {
-		tc.put("important", "value");
-		return tc;
-	};
+	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r) -> McpTransportContext
+		.create(Map.of("important", "value"));
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
index 987c43663..104349116 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
@@ -54,7 +55,7 @@ void setUp() {
 		clientInfo = new McpSchema.Implementation("test-client", "1.0.0");
 
 		exchange = new McpAsyncServerExchange("testSessionId", mockSession, clientCapabilities, clientInfo,
-				new DefaultMcpTransportContext());
+				McpTransportContext.EMPTY);
 	}
 
 	@Test

From a5fd1ebff54c54e7c4fe122c4aadc185d6bd98dc Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Wed, 3 Sep 2025 16:36:46 +0200
Subject: [PATCH 059/125] Use static container in all client and transport
 tests (#531)

- This allows reusing the containerized MCP server for all tests in a
  single class, significantly speeding up the tests, roughly 10x.

Signed-off-by: Daniel Garnier-Moiroux 
---
 ...ebClientStreamableHttpAsyncClientTests.java | 12 +++++++-----
 ...WebClientStreamableHttpSyncClientTests.java | 12 +++++++-----
 .../client/WebFluxSseMcpAsyncClientTests.java  | 12 +++++++-----
 .../client/WebFluxSseMcpSyncClientTests.java   | 12 +++++++-----
 .../WebFluxSseClientTransportTests.java        | 18 ++++++++++--------
 .../client/AbstractMcpAsyncClientTests.java    | 16 ----------------
 .../client/AbstractMcpSyncClientTests.java     | 17 -----------------
 .../client/AbstractMcpAsyncClientTests.java    | 16 ----------------
 .../client/AbstractMcpSyncClientTests.java     | 17 -----------------
 ...tpClientStreamableHttpAsyncClientTests.java | 14 ++++++++------
 ...ttpClientStreamableHttpSyncClientTests.java | 13 +++++++------
 .../client/HttpSseMcpAsyncClientTests.java     | 14 ++++++++------
 .../client/HttpSseMcpSyncClientTests.java      | 15 ++++++++-------
 13 files changed, 69 insertions(+), 119 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
index f8a16c153..8ef8177eb 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.client;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Timeout;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.testcontainers.containers.GenericContainer;
@@ -19,7 +21,7 @@ public class WebClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncCli
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -30,15 +32,15 @@ protected McpClientTransport createMcpTransport() {
 		return WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl(host)).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	public void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
index 5e9960d0e..1b252e27b 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.client;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Timeout;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.testcontainers.containers.GenericContainer;
@@ -19,7 +21,7 @@ public class WebClientStreamableHttpSyncClientTests extends AbstractMcpSyncClien
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -30,15 +32,15 @@ protected McpClientTransport createMcpTransport() {
 		return WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl(host)).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	public void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
index 0edf4cd54..e32222357 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
@@ -6,6 +6,8 @@
 
 import java.time.Duration;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Timeout;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.testcontainers.containers.GenericContainer;
@@ -26,7 +28,7 @@ class WebFluxSseMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -37,15 +39,15 @@ protected McpClientTransport createMcpTransport() {
 		return WebFluxSseClientTransport.builder(WebClient.builder().baseUrl(host)).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	public void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
index 9b0959a35..a62dea267 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
@@ -8,6 +8,8 @@
 
 import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
 import io.modelcontextprotocol.spec.McpClientTransport;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
@@ -26,7 +28,7 @@ class WebFluxSseMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -37,15 +39,15 @@ protected McpClientTransport createMcpTransport() {
 		return WebFluxSseClientTransport.builder(WebClient.builder().baseUrl(host)).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	protected void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
index 1cf5dffe2..53f54d121 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
@@ -13,7 +13,9 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCRequest;
+import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Timeout;
@@ -42,7 +44,7 @@ class WebFluxSseClientTransportTests {
 	static String host = "http://localhost:3001";
 
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -95,15 +97,20 @@ public void simulateMessageEvent(String jsonMessage) {
 
 	}
 
-	void startContainer() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
+	@AfterAll
+	static void cleanup() {
+		container.stop();
+	}
+
 	@BeforeEach
 	void setUp() {
-		startContainer();
 		webClientBuilder = WebClient.builder().baseUrl(host);
 		objectMapper = new ObjectMapper();
 		transport = new TestSseClientTransport(webClientBuilder, objectMapper);
@@ -115,11 +122,6 @@ void afterEach() {
 		if (transport != null) {
 			assertThatCode(() -> transport.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 		}
-		cleanup();
-	}
-
-	void cleanup() {
-		container.stop();
 	}
 
 	@Test
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index ea3739da5..8902a53b3 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -67,12 +67,6 @@ public abstract class AbstractMcpAsyncClientTests {
 
 	abstract protected McpClientTransport createMcpTransport();
 
-	protected void onStart() {
-	}
-
-	protected void onClose() {
-	}
-
 	protected Duration getRequestTimeout() {
 		return Duration.ofSeconds(14);
 	}
@@ -117,16 +111,6 @@ void withClient(McpClientTransport transport, Function void verifyNotificationSucceedsWithImplicitInitialization(Function> operation,
 			String action) {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 175a0107c..8eb6ec248 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -66,12 +66,6 @@ public abstract class AbstractMcpSyncClientTests {
 
 	abstract protected McpClientTransport createMcpTransport();
 
-	protected void onStart() {
-	}
-
-	protected void onClose() {
-	}
-
 	protected Duration getRequestTimeout() {
 		return Duration.ofSeconds(14);
 	}
@@ -114,17 +108,6 @@ void withClient(McpClientTransport transport, Function void verifyNotificationSucceedsWithImplicitInitialization(Consumer operation, String action) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 3626d8ca0..af802df48 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -68,12 +68,6 @@ public abstract class AbstractMcpAsyncClientTests {
 
 	abstract protected McpClientTransport createMcpTransport();
 
-	protected void onStart() {
-	}
-
-	protected void onClose() {
-	}
-
 	protected Duration getRequestTimeout() {
 		return Duration.ofSeconds(14);
 	}
@@ -118,16 +112,6 @@ void withClient(McpClientTransport transport, Function void verifyNotificationSucceedsWithImplicitInitialization(Function> operation,
 			String action) {
 		withClient(createMcpTransport(), mcpAsyncClient -> {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index c74255060..4f6551199 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -67,12 +67,6 @@ public abstract class AbstractMcpSyncClientTests {
 
 	abstract protected McpClientTransport createMcpTransport();
 
-	protected void onStart() {
-	}
-
-	protected void onClose() {
-	}
-
 	protected Duration getRequestTimeout() {
 		return Duration.ofSeconds(14);
 	}
@@ -115,17 +109,6 @@ void withClient(McpClientTransport transport, Function void verifyNotificationSucceedsWithImplicitInitialization(Consumer operation, String action) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
index aef2ab8dd..647e27d30 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.client;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
@@ -14,11 +16,11 @@
 @Timeout(15)
 public class HttpClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
-	private String host = "http://localhost:3001";
+	private static String host = "http://localhost:3001";
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -30,15 +32,15 @@ protected McpClientTransport createMcpTransport() {
 		return HttpClientStreamableHttpTransport.builder(host).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	public void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
index 6f3b58e3d..e798db82e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
@@ -7,6 +7,8 @@
 import java.net.URI;
 import java.util.Map;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
@@ -17,7 +19,6 @@
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpClientTransport;
 
-import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.atLeastOnce;
@@ -31,7 +32,7 @@ public class HttpClientStreamableHttpSyncClientTests extends AbstractMcpSyncClie
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -44,15 +45,15 @@ protected McpClientTransport createMcpTransport() {
 		return HttpClientStreamableHttpTransport.builder(host).httpRequestCustomizer(requestCustomizer).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	public void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
index 6cb3f7b65..8827f7ec7 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.client;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
@@ -19,11 +21,11 @@
 @Timeout(15)
 class HttpSseMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
-	String host = "http://localhost:3004";
+	private static String host = "http://localhost:3004";
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -34,15 +36,15 @@ protected McpClientTransport createMcpTransport() {
 		return HttpClientSseClientTransport.builder(host).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	protected void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
index 4091d7a5e..38c6fdc4e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
@@ -7,6 +7,8 @@
 import java.net.URI;
 import java.util.Map;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
@@ -17,7 +19,6 @@
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpClientTransport;
 
-import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.ArgumentMatchers.isNull;
@@ -33,11 +34,11 @@
 @Timeout(15) // Giving extra time beyond the client timeout
 class HttpSseMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
-	String host = "http://localhost:3003";
+	static String host = "http://localhost:3003";
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
@@ -50,15 +51,15 @@ protected McpClientTransport createMcpTransport() {
 		return HttpClientSseClientTransport.builder(host).httpRequestCustomizer(requestCustomizer).build();
 	}
 
-	@Override
-	protected void onStart() {
+	@BeforeAll
+	static void startContainer() {
 		container.start();
 		int port = container.getMappedPort(3001);
 		host = "http://" + container.getHost() + ":" + port;
 	}
 
-	@Override
-	protected void onClose() {
+	@AfterAll
+	static void stopContainer() {
 		container.stop();
 	}
 

From 02b8c4bcfffdde281ff69230ef38e4ae1a8ff002 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Thu, 4 Sep 2025 09:27:01 +0200
Subject: [PATCH 060/125] test: Add additional MCP transport context
 integration tests (#529)

- Add integration tests for transport context propagation between MCP clients and servers
- Test both sync and async server implementations across all transport types (stateless, streamable, SSE)
- Cover Spring WebFlux and WebMVC environments with dedicated test suites
- Validate context flow through HTTP headers for authentication, correlation IDs, and metadata
- Rename existing McpTransportContextIntegrationTests to SyncServerMcpTransportContextIntegrationTests for clarity
- Add proper resource cleanup for async clients in teardown methods

Signed-off-by: Christian Tzolov 
---
 ...erMcpTransportContextIntegrationTests.java | 273 ++++++++++++++++
 ...erMcpTransportContextIntegrationTests.java | 273 ++++++++++++++++
 mcp-spring/mcp-spring-webmvc/pom.xml          |   2 +-
 .../McpTransportContextIntegrationTests.java  | 306 ++++++++++++++++++
 ...erMcpTransportContextIntegrationTests.java | 284 ++++++++++++++++
 ...rMcpTransportContextIntegrationTests.java} |   8 +-
 6 files changed, 1144 insertions(+), 2 deletions(-)
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
 rename mcp/src/test/java/io/modelcontextprotocol/common/{McpTransportContextIntegrationTests.java => SyncServerMcpTransportContextIntegrationTests.java} (97%)

diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
new file mode 100644
index 000000000..f3e2d3626
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
@@ -0,0 +1,273 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.common;
+
+import java.util.Map;
+import java.util.function.BiFunction;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.McpAsyncClient;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
+import io.modelcontextprotocol.server.McpAsyncServerExchange;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.WebFluxStatelessServerTransport;
+import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpSchema;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+import reactor.core.publisher.Mono;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+import reactor.test.StepVerifier;
+
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.function.client.ClientRequest;
+import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.server.RouterFunction;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import org.springframework.web.reactive.function.server.ServerRequest;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Integration tests for {@link McpTransportContext} propagation between MCP clients and
+ * async servers using Spring WebFlux infrastructure.
+ *
+ * 

+ * This test class validates the end-to-end flow of transport context propagation in MCP
+ * communication for asynchronous client and server implementations. It tests various
+ * combinations of client types and server transport mechanisms (stateless, streamable,
+ * SSE) to ensure proper context handling across different configurations.
+ *
+ * 
Context Propagation Flow

+ * 
    
+ * 
  1. Client sets a value in its transport context via thread-local Reactor context
    2. 
+ * 
  2. Client-side context provider extracts the value and adds it as an HTTP header to
+ * the request
    3. 
+ * 
  3. Server-side context extractor reads the header from the incoming request
    4. 
+ * 
  4. Server handler receives the extracted context and returns the value as the tool
+ * call result
    5. 
+ * 
  5. Test verifies the round-trip context propagation was successful
    6. 
+ * 

+ *
+ * @author Daniel Garnier-Moiroux
+ * @author Christian Tzolov
+ */
+@Timeout(15)
+public class AsyncServerMcpTransportContextIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String HEADER_NAME = "x-test";
+
+	// Async client context provider
+	ExchangeFilterFunction asyncClientContextProvider = (request, next) -> Mono.deferContextual(ctx -> {
+		var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+		// // do stuff with the context
+		var headerValue = transportContext.get("client-side-header-value");
+		if (headerValue == null) {
+			return next.exchange(request);
+		}
+		var reqWithHeader = ClientRequest.from(request).header(HEADER_NAME, headerValue.toString()).build();
+		return next.exchange(reqWithHeader);
+	});
+
+	// Tools
+	private final McpSchema.Tool tool = McpSchema.Tool.builder()
+		.name("test-tool")
+		.description("return the value of the x-test header from call tool request")
+		.build();
+
+	private final BiFunction> asyncStatelessHandler = (
+			transportContext, request) -> {
+		return Mono
+			.just(new McpSchema.CallToolResult(transportContext.get("server-side-header-value").toString(), null));
+	};
+
+	private final BiFunction> asyncStatefulHandler = (
+			exchange, request) -> {
+		return asyncStatelessHandler.apply(exchange.transportContext(), request);
+	};
+
+	// Server context extractor
+	private final McpTransportContextExtractor serverContextExtractor = (ServerRequest r) -> {
+		var headerValue = r.headers().firstHeader(HEADER_NAME);
+		return headerValue != null ? McpTransportContext.create(Map.of("server-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	// Server transports
+	private final WebFluxStatelessServerTransport statelessServerTransport = WebFluxStatelessServerTransport.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final WebFluxStreamableServerTransportProvider streamableServerTransport = WebFluxStreamableServerTransportProvider
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final WebFluxSseServerTransportProvider sseServerTransport = WebFluxSseServerTransportProvider.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.messageEndpoint("/mcp/message")
+		.build();
+
+	// Async clients
+	private final McpAsyncClient asyncStreamableClient = McpClient
+		.async(WebClientStreamableHttpTransport
+			.builder(WebClient.builder().baseUrl("http://localhost:" + PORT).filter(asyncClientContextProvider))
+			.build())
+		.build();
+
+	private final McpAsyncClient asyncSseClient = McpClient
+		.async(WebFluxSseClientTransport
+			.builder(WebClient.builder().baseUrl("http://localhost:" + PORT).filter(asyncClientContextProvider))
+			.build())
+		.build();
+
+	private DisposableServer httpServer;
+
+	@AfterEach
+	public void after() {
+		if (statelessServerTransport != null) {
+			statelessServerTransport.closeGracefully().block();
+		}
+		if (streamableServerTransport != null) {
+			streamableServerTransport.closeGracefully().block();
+		}
+		if (sseServerTransport != null) {
+			sseServerTransport.closeGracefully().block();
+		}
+		if (asyncStreamableClient != null) {
+			asyncStreamableClient.closeGracefully().block();
+		}
+		if (asyncSseClient != null) {
+			asyncSseClient.closeGracefully().block();
+		}
+		stopHttpServer();
+	}
+
+	@Test
+	void asyncClientStatelessServer() {
+
+		startHttpServer(statelessServerTransport.getRouterFunction());
+
+		var mcpServer = McpServer.async(statelessServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpStatelessServerFeatures.AsyncToolSpecification(tool, asyncStatelessHandler))
+			.build();
+
+		StepVerifier.create(asyncStreamableClient.initialize()).assertNext(initResult -> {
+			assertThat(initResult).isNotNull();
+		}).verifyComplete();
+
+		// Test tool call with context
+		StepVerifier
+			.create(asyncStreamableClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()))
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY,
+						McpTransportContext.create(Map.of("client-side-header-value", "some important value")))))
+			.assertNext(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.content()).hasSize(1)
+					.first()
+					.extracting(McpSchema.TextContent.class::cast)
+					.extracting(McpSchema.TextContent::text)
+					.isEqualTo("some important value");
+			})
+			.verifyComplete();
+
+		mcpServer.close();
+	}
+
+	@Test
+	void asyncClientStreamableServer() {
+
+		startHttpServer(streamableServerTransport.getRouterFunction());
+
+		var mcpServer = McpServer.async(streamableServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.AsyncToolSpecification(tool, null, asyncStatefulHandler))
+			.build();
+
+		StepVerifier.create(asyncStreamableClient.initialize()).assertNext(initResult -> {
+			assertThat(initResult).isNotNull();
+		}).verifyComplete();
+
+		// Test tool call with context
+		StepVerifier
+			.create(asyncStreamableClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()))
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY,
+						McpTransportContext.create(Map.of("client-side-header-value", "some important value")))))
+			.assertNext(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.content()).hasSize(1)
+					.first()
+					.extracting(McpSchema.TextContent.class::cast)
+					.extracting(McpSchema.TextContent::text)
+					.isEqualTo("some important value");
+			})
+			.verifyComplete();
+
+		mcpServer.close();
+	}
+
+	@Test
+	void asyncClientSseServer() {
+
+		startHttpServer(sseServerTransport.getRouterFunction());
+
+		var mcpServer = McpServer.async(sseServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.AsyncToolSpecification(tool, null, asyncStatefulHandler))
+			.build();
+
+		StepVerifier.create(asyncSseClient.initialize()).assertNext(initResult -> {
+			assertThat(initResult).isNotNull();
+		}).verifyComplete();
+
+		// Test tool call with context
+		StepVerifier
+			.create(asyncSseClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()))
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY,
+						McpTransportContext.create(Map.of("client-side-header-value", "some important value")))))
+			.assertNext(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.content()).hasSize(1)
+					.first()
+					.extracting(McpSchema.TextContent.class::cast)
+					.extracting(McpSchema.TextContent::text)
+					.isEqualTo("some important value");
+			})
+			.verifyComplete();
+
+		mcpServer.close();
+	}
+
+	private void startHttpServer(RouterFunction routerFunction) {
+
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(routerFunction);
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+	}
+
+	private void stopHttpServer() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
new file mode 100644
index 000000000..865192489
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
@@ -0,0 +1,273 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.common;
+
+import java.util.Map;
+import java.util.function.BiFunction;
+import java.util.function.Supplier;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.McpSyncClient;
+import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.WebFluxStatelessServerTransport;
+import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpSchema;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+import reactor.core.publisher.Mono;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.function.client.ClientRequest;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.server.RouterFunction;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import org.springframework.web.reactive.function.server.ServerRequest;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Integration tests for {@link McpTransportContext} propagation between MCP client and
+ * server using synchronous operations in a Spring WebFlux environment.
+ * 

+ * This test class validates the end-to-end flow of transport context propagation across
+ * different WebFlux-based MCP transport implementations
+ *
+ * 

+ * The test scenario follows these steps:
+ * 
    
+ * 
  1. The client stores a value in a thread-local variable
    2. 
+ * 
  2. The client's transport context provider reads this value and includes it in the MCP
+ * context
    3. 
+ * 
  3. A WebClient filter extracts the context value and adds it as an HTTP header
+ * (x-test)
    4. 
+ * 
  4. The server's {@link McpTransportContextExtractor} reads the header from the
+ * request
    5. 
+ * 
  5. The server returns the header value as the tool call result, validating the
+ * round-trip
    6. 
+ * 

+ *
+ * 

+ * This test demonstrates how custom context can be propagated through HTTP headers in a
+ * reactive WebFlux environment, enabling features like authentication tokens, correlation
+ * IDs, or other metadata to flow between MCP client and server.
+ *
+ * @author Daniel Garnier-Moiroux
+ * @author Christian Tzolov
+ * @since 1.0.0
+ * @see McpTransportContext
+ * @see McpTransportContextExtractor
+ * @see WebFluxStatelessServerTransport
+ * @see WebFluxStreamableServerTransportProvider
+ * @see WebFluxSseServerTransportProvider
+ */
+@Timeout(15)
+public class SyncServerMcpTransportContextIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final ThreadLocal CLIENT_SIDE_HEADER_VALUE_HOLDER = new ThreadLocal<>();
+
+	private static final String HEADER_NAME = "x-test";
+
+	private final Supplier clientContextProvider = () -> {
+		var headerValue = CLIENT_SIDE_HEADER_VALUE_HOLDER.get();
+		return headerValue != null ? McpTransportContext.create(Map.of("client-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	private final BiFunction statelessHandler = (
+			transportContext, request) -> {
+		return new McpSchema.CallToolResult(transportContext.get("server-side-header-value").toString(), null);
+	};
+
+	private final BiFunction statefulHandler = (
+			exchange, request) -> statelessHandler.apply(exchange.transportContext(), request);
+
+	private final McpTransportContextExtractor serverContextExtractor = (ServerRequest r) -> {
+		var headerValue = r.headers().firstHeader(HEADER_NAME);
+		return headerValue != null ? McpTransportContext.create(Map.of("server-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	private final WebFluxStatelessServerTransport statelessServerTransport = WebFluxStatelessServerTransport.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final WebFluxStreamableServerTransportProvider streamableServerTransport = WebFluxStreamableServerTransportProvider
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final WebFluxSseServerTransportProvider sseServerTransport = WebFluxSseServerTransportProvider.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.messageEndpoint("/mcp/message")
+		.build();
+
+	private final McpSyncClient streamableClient = McpClient
+		.sync(WebClientStreamableHttpTransport.builder(WebClient.builder()
+			.baseUrl("http://localhost:" + PORT)
+			.filter((request, next) -> Mono.deferContextual(ctx -> {
+				var context = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+				// // do stuff with the context
+				var headerValue = context.get("client-side-header-value");
+				if (headerValue == null) {
+					return next.exchange(request);
+				}
+				var reqWithHeader = ClientRequest.from(request).header(HEADER_NAME, headerValue.toString()).build();
+				return next.exchange(reqWithHeader);
+			}))).build())
+		.transportContextProvider(clientContextProvider)
+		.build();
+
+	private final McpSyncClient sseClient = McpClient.sync(WebFluxSseClientTransport.builder(WebClient.builder()
+		.baseUrl("http://localhost:" + PORT)
+		.filter((request, next) -> Mono.deferContextual(ctx -> {
+			var context = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
+			// // do stuff with the context
+			var headerValue = context.get("client-side-header-value");
+			if (headerValue == null) {
+				return next.exchange(request);
+			}
+			var reqWithHeader = ClientRequest.from(request).header(HEADER_NAME, headerValue.toString()).build();
+			return next.exchange(reqWithHeader);
+		}))).build()).transportContextProvider(clientContextProvider).build();
+
+	private final McpSchema.Tool tool = McpSchema.Tool.builder()
+		.name("test-tool")
+		.description("return the value of the x-test header from call tool request")
+		.build();
+
+	private DisposableServer httpServer;
+
+	@AfterEach
+	public void after() {
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.remove();
+		if (statelessServerTransport != null) {
+			statelessServerTransport.closeGracefully().block();
+		}
+		if (streamableServerTransport != null) {
+			streamableServerTransport.closeGracefully().block();
+		}
+		if (sseServerTransport != null) {
+			sseServerTransport.closeGracefully().block();
+		}
+		if (streamableClient != null) {
+			streamableClient.closeGracefully();
+		}
+		if (sseClient != null) {
+			sseClient.closeGracefully();
+		}
+		stopHttpServer();
+	}
+
+	@Test
+	void statelessServer() {
+
+		startHttpServer(statelessServerTransport.getRouterFunction());
+
+		var mcpServer = McpServer.sync(statelessServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpStatelessServerFeatures.SyncToolSpecification(tool, statelessHandler))
+			.build();
+
+		McpSchema.InitializeResult initResult = streamableClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = streamableClient
+			.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+
+		mcpServer.close();
+	}
+
+	@Test
+	void streamableServer() {
+
+		startHttpServer(streamableServerTransport.getRouterFunction());
+
+		var mcpServer = McpServer.sync(streamableServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.SyncToolSpecification(tool, null, statefulHandler))
+			.build();
+
+		McpSchema.InitializeResult initResult = streamableClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = streamableClient
+			.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+
+		mcpServer.close();
+	}
+
+	@Test
+	void sseServer() {
+		startHttpServer(sseServerTransport.getRouterFunction());
+
+		var mcpServer = McpServer.sync(sseServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.SyncToolSpecification(tool, null, statefulHandler))
+			.build();
+
+		McpSchema.InitializeResult initResult = sseClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = sseClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+
+		mcpServer.close();
+	}
+
+	private void startHttpServer(RouterFunction routerFunction) {
+
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(routerFunction);
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+	}
+
+	private void stopHttpServer() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index ea262d3a1..170309211 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -41,7 +41,7 @@
 			test
 		
 
-				
+		
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
 			0.12.0-SNAPSHOT
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
new file mode 100644
index 000000000..1f5f1cc0c
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
@@ -0,0 +1,306 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.common;
+
+import java.util.Map;
+import java.util.function.BiFunction;
+import java.util.function.Supplier;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.McpSyncClient;
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.McpStatelessSyncServer;
+import io.modelcontextprotocol.server.McpSyncServer;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.TomcatTestUtil;
+import io.modelcontextprotocol.server.TomcatTestUtil.TomcatServer;
+import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.WebMvcStatelessServerTransport;
+import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpSchema;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerRequest;
+import org.springframework.web.servlet.function.ServerResponse;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Integration tests for {@link McpTransportContext} propagation between MCP clients and
+ * servers using Spring WebMVC transport implementations.
+ *
+ * 

+ * This test class validates the end-to-end flow of transport context propagation across
+ * different MCP transport mechanisms in a Spring WebMVC environment. It demonstrates how
+ * contextual information can be passed from client to server through HTTP headers and
+ * properly extracted and utilized on the server side.
+ *
+ * 
Transport Types Tested

+ * 
    
+ * 
  • Stateless: Tests context propagation with
+ * {@link WebMvcStatelessServerTransport} where each request is independent
    • 
+ * 
  • Streamable HTTP: Tests context propagation with
+ * {@link WebMvcStreamableServerTransportProvider} supporting stateful server
+ * sessions
    • 
+ * 
  • Server-Sent Events (SSE): Tests context propagation with
+ * {@link WebMvcSseServerTransportProvider} for long-lived connections
    • 
+ * 

+ *
+ * @author Daniel Garnier-Moiroux
+ * @author Christian Tzolov
+ */
+@Timeout(15)
+public class McpTransportContextIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private TomcatServer tomcatServer;
+
+	private static final ThreadLocal CLIENT_SIDE_HEADER_VALUE_HOLDER = new ThreadLocal<>();
+
+	private static final String HEADER_NAME = "x-test";
+
+	private final Supplier clientContextProvider = () -> {
+		var headerValue = CLIENT_SIDE_HEADER_VALUE_HOLDER.get();
+		return headerValue != null ? McpTransportContext.create(Map.of("client-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	private final McpSyncHttpClientRequestCustomizer clientRequestCustomizer = (builder, method, endpoint, body,
+			context) -> {
+		var headerValue = context.get("client-side-header-value");
+		if (headerValue != null) {
+			builder.header(HEADER_NAME, headerValue.toString());
+		}
+	};
+
+	private static final BiFunction statelessHandler = (
+			transportContext,
+			request) -> new McpSchema.CallToolResult(transportContext.get("server-side-header-value").toString(), null);
+
+	private static final BiFunction statefulHandler = (
+			exchange, request) -> statelessHandler.apply(exchange.transportContext(), request);
+
+	private static McpTransportContextExtractor serverContextExtractor = (ServerRequest r) -> {
+		String headerValue = r.servletRequest().getHeader(HEADER_NAME);
+		return headerValue != null ? McpTransportContext.create(Map.of("server-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	private final McpSyncClient streamableClient = McpClient
+		.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+			.httpRequestCustomizer(clientRequestCustomizer)
+			.build())
+		.transportContextProvider(clientContextProvider)
+		.build();
+
+	private final McpSyncClient sseClient = McpClient
+		.sync(HttpClientSseClientTransport.builder("http://localhost:" + PORT)
+			.httpRequestCustomizer(clientRequestCustomizer)
+			.build())
+		.transportContextProvider(clientContextProvider)
+		.build();
+
+	private static final McpSchema.Tool tool = McpSchema.Tool.builder()
+		.name("test-tool")
+		.description("return the value of the x-test header from call tool request")
+		.build();
+
+	@AfterEach
+	public void after() {
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.remove();
+		if (streamableClient != null) {
+			streamableClient.closeGracefully();
+		}
+		if (sseClient != null) {
+			sseClient.closeGracefully();
+		}
+		stopTomcat();
+	}
+
+	@Test
+	void statelessServer() {
+		startTomcat(TestStatelessConfig.class);
+
+		McpSchema.InitializeResult initResult = streamableClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = streamableClient
+			.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+	}
+
+	@Test
+	void streamableServer() {
+
+		startTomcat(TestStreamableHttpConfig.class);
+
+		McpSchema.InitializeResult initResult = streamableClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = streamableClient
+			.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+	}
+
+	@Test
+	void sseServer() {
+		startTomcat(TestSseConfig.class);
+
+		McpSchema.InitializeResult initResult = sseClient.initialize();
+		assertThat(initResult).isNotNull();
+
+		CLIENT_SIDE_HEADER_VALUE_HOLDER.set("some important value");
+		McpSchema.CallToolResult response = sseClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("some important value");
+	}
+
+	private void startTomcat(Class componentClass) {
+		tomcatServer = TomcatTestUtil.createTomcatServer("", PORT, componentClass);
+		try {
+			tomcatServer.tomcat().start();
+			assertThat(tomcatServer.tomcat().getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+	}
+
+	private void stopTomcat() {
+		if (tomcatServer != null && tomcatServer.tomcat() != null) {
+			try {
+				tomcatServer.tomcat().stop();
+				tomcatServer.tomcat().destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	@Configuration
+	@EnableWebMvc
+	static class TestStatelessConfig {
+
+		@Bean
+		public WebMvcStatelessServerTransport webMvcStatelessServerTransport() {
+
+			return WebMvcStatelessServerTransport.builder()
+				.objectMapper(new ObjectMapper())
+				.contextExtractor(serverContextExtractor)
+				.build();
+		}
+
+		@Bean
+		public RouterFunction routerFunction(WebMvcStatelessServerTransport transportProvider) {
+			return transportProvider.getRouterFunction();
+		}
+
+		@Bean
+		public McpStatelessSyncServer mcpStatelessServer(WebMvcStatelessServerTransport transportProvider) {
+			return McpServer.sync(transportProvider)
+				.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+				.tools(new McpStatelessServerFeatures.SyncToolSpecification(tool, statelessHandler))
+				.build();
+		}
+
+	}
+
+	@Configuration
+	@EnableWebMvc
+	static class TestStreamableHttpConfig {
+
+		@Bean
+		public WebMvcStreamableServerTransportProvider webMvcStreamableServerTransport() {
+
+			return WebMvcStreamableServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.contextExtractor(serverContextExtractor)
+				.build();
+		}
+
+		@Bean
+		public RouterFunction routerFunction(
+				WebMvcStreamableServerTransportProvider transportProvider) {
+			return transportProvider.getRouterFunction();
+		}
+
+		@Bean
+		public McpSyncServer mcpStreamableServer(WebMvcStreamableServerTransportProvider transportProvider) {
+			return McpServer.sync(transportProvider)
+				.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+				.tools(new McpServerFeatures.SyncToolSpecification(tool, null, statefulHandler))
+				.build();
+		}
+
+	}
+
+	@Configuration
+	@EnableWebMvc
+	static class TestSseConfig {
+
+		@Bean
+		public WebMvcSseServerTransportProvider webMvcSseServerTransport() {
+
+			return WebMvcSseServerTransportProvider.builder()
+				.objectMapper(new ObjectMapper())
+				.contextExtractor(serverContextExtractor)
+				.messageEndpoint("/mcp/message")
+				.build();
+		}
+
+		@Bean
+		public RouterFunction routerFunction(WebMvcSseServerTransportProvider transportProvider) {
+			return transportProvider.getRouterFunction();
+		}
+
+		@Bean
+		public McpSyncServer mcpSseServer(WebMvcSseServerTransportProvider transportProvider) {
+			return McpServer.sync(transportProvider)
+				.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+				.tools(new McpServerFeatures.SyncToolSpecification(tool, null, statefulHandler))
+				.build();
+
+		}
+
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
new file mode 100644
index 000000000..fb19c62f7
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
@@ -0,0 +1,284 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.common;
+
+import java.util.Map;
+import java.util.function.BiFunction;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.client.McpAsyncClient;
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
+import io.modelcontextprotocol.server.McpAsyncServerExchange;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures;
+import io.modelcontextprotocol.server.McpTransportContextExtractor;
+import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
+import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.McpSchema;
+import jakarta.servlet.Servlet;
+import jakarta.servlet.http.HttpServletRequest;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Integration tests for {@link McpTransportContext} propagation between MCP clients and
+ * async servers.
+ *
+ * 

+ * This test class validates the end-to-end flow of transport context propagation in MCP
+ * communication, demonstrating how contextual information can be passed from client to
+ * server through HTTP headers and accessed within server-side handlers.
+ *
+ * 
Test Scenarios

+ * 

+ * The tests cover multiple transport configurations with async servers:
+ * 
    
+ * 
  • Stateless server with async streamable HTTP clients
    • 
+ * 
  • Streamable server with async streamable HTTP clients
    • 
+ * 
  • SSE (Server-Sent Events) server with async SSE clients
    • 
+ * 

+ *
+ * 
Context Propagation Flow

+ * 
    
+ * 
  1. Client-side: Context data is stored in the Reactor Context and injected into HTTP
+ * headers via {@link McpSyncHttpClientRequestCustomizer}
    2. 
+ * 
  2. Transport: The context travels as HTTP headers (specifically "x-test" header in
+ * these tests)
    3. 
+ * 
  3. Server-side: A {@link McpTransportContextExtractor} extracts the header value and
+ * makes it available to request handlers through {@link McpTransportContext}
    4. 
+ * 
  4. Verification: The server echoes back the received context value as the tool call
+ * result
    5. 
+ * 

+ *
+ * 

+ * All tests use an embedded Tomcat server running on a dynamically allocated port to
+ * ensure isolation and prevent port conflicts during parallel test execution.
+ *
+ * @author Daniel Garnier-Moiroux
+ * @author Christian Tzolov
+ */
+@Timeout(15)
+public class AsyncServerMcpTransportContextIntegrationTests {
+
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
+	private Tomcat tomcat;
+
+	private static final String HEADER_NAME = "x-test";
+
+	private final McpAsyncHttpClientRequestCustomizer asyncClientRequestCustomizer = (builder, method, endpoint, body,
+			context) -> {
+		var headerValue = context.get("client-side-header-value");
+		if (headerValue != null) {
+			builder.header(HEADER_NAME, headerValue.toString());
+		}
+		return Mono.just(builder);
+	};
+
+	private final McpTransportContextExtractor serverContextExtractor = (HttpServletRequest r) -> {
+		var headerValue = r.getHeader(HEADER_NAME);
+		return headerValue != null ? McpTransportContext.create(Map.of("server-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};
+
+	private final HttpServletStatelessServerTransport statelessServerTransport = HttpServletStatelessServerTransport
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final HttpServletStreamableServerTransportProvider streamableServerTransport = HttpServletStreamableServerTransportProvider
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.build();
+
+	private final HttpServletSseServerTransportProvider sseServerTransport = HttpServletSseServerTransportProvider
+		.builder()
+		.objectMapper(new ObjectMapper())
+		.contextExtractor(serverContextExtractor)
+		.messageEndpoint("/message")
+		.build();
+
+	private final McpAsyncClient asyncStreamableClient = McpClient
+		.async(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+			.asyncHttpRequestCustomizer(asyncClientRequestCustomizer)
+			.build())
+		.build();
+
+	private final McpAsyncClient asyncSseClient = McpClient
+		.async(HttpClientSseClientTransport.builder("http://localhost:" + PORT)
+			.asyncHttpRequestCustomizer(asyncClientRequestCustomizer)
+			.build())
+		.build();
+
+	private final McpSchema.Tool tool = McpSchema.Tool.builder()
+		.name("test-tool")
+		.description("return the value of the x-test header from call tool request")
+		.build();
+
+	private final BiFunction> asyncStatelessHandler = (
+			transportContext, request) -> {
+		return Mono
+			.just(new McpSchema.CallToolResult(transportContext.get("server-side-header-value").toString(), null));
+	};
+
+	private final BiFunction> asyncStatefulHandler = (
+			exchange, request) -> {
+		return asyncStatelessHandler.apply(exchange.transportContext(), request);
+	};
+
+	@AfterEach
+	public void after() {
+		if (statelessServerTransport != null) {
+			statelessServerTransport.closeGracefully().block();
+		}
+		if (streamableServerTransport != null) {
+			streamableServerTransport.closeGracefully().block();
+		}
+		if (sseServerTransport != null) {
+			sseServerTransport.closeGracefully().block();
+		}
+		if (asyncStreamableClient != null) {
+			asyncStreamableClient.closeGracefully().block();
+		}
+		if (asyncSseClient != null) {
+			asyncSseClient.closeGracefully().block();
+		}
+		stopTomcat();
+	}
+
+	@Test
+	void asyncClinetStatelessServer() {
+		startTomcat(statelessServerTransport);
+
+		var mcpServer = McpServer.async(statelessServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpStatelessServerFeatures.AsyncToolSpecification(tool, asyncStatelessHandler))
+			.build();
+
+		StepVerifier.create(asyncStreamableClient.initialize()).assertNext(initResult -> {
+			assertThat(initResult).isNotNull();
+		}).verifyComplete();
+
+		// Test tool call with context
+		StepVerifier
+			.create(asyncStreamableClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()))
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY,
+						McpTransportContext.create(Map.of("client-side-header-value", "some important value")))))
+			.assertNext(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.content()).hasSize(1)
+					.first()
+					.extracting(McpSchema.TextContent.class::cast)
+					.extracting(McpSchema.TextContent::text)
+					.isEqualTo("some important value");
+			})
+			.verifyComplete();
+
+		mcpServer.close();
+	}
+
+	@Test
+	void asyncClientStreamableServer() {
+		startTomcat(streamableServerTransport);
+
+		var mcpServer = McpServer.async(streamableServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.AsyncToolSpecification(tool, null, asyncStatefulHandler))
+			.build();
+
+		StepVerifier.create(asyncStreamableClient.initialize()).assertNext(initResult -> {
+			assertThat(initResult).isNotNull();
+		}).verifyComplete();
+
+		// Test tool call with context
+		StepVerifier
+			.create(asyncStreamableClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()))
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY,
+						McpTransportContext.create(Map.of("client-side-header-value", "some important value")))))
+			.assertNext(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.content()).hasSize(1)
+					.first()
+					.extracting(McpSchema.TextContent.class::cast)
+					.extracting(McpSchema.TextContent::text)
+					.isEqualTo("some important value");
+			})
+			.verifyComplete();
+
+		mcpServer.close();
+	}
+
+	@Test
+	void asyncClientSseServer() {
+		startTomcat(sseServerTransport);
+
+		var mcpServer = McpServer.async(sseServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpServerFeatures.AsyncToolSpecification(tool, null, asyncStatefulHandler))
+			.build();
+
+		StepVerifier.create(asyncSseClient.initialize()).assertNext(initResult -> {
+			assertThat(initResult).isNotNull();
+		}).verifyComplete();
+
+		// Test tool call with context
+		StepVerifier
+			.create(asyncSseClient.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()))
+				.contextWrite(ctx -> ctx.put(McpTransportContext.KEY,
+						McpTransportContext.create(Map.of("client-side-header-value", "some important value")))))
+			.assertNext(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.content()).hasSize(1)
+					.first()
+					.extracting(McpSchema.TextContent.class::cast)
+					.extracting(McpSchema.TextContent::text)
+					.isEqualTo("some important value");
+			})
+			.verifyComplete();
+
+		mcpServer.close();
+	}
+
+	private void startTomcat(Servlet transport) {
+		tomcat = TomcatTestUtil.createTomcatServer("", PORT, transport);
+		try {
+			tomcat.start();
+			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+	}
+
+	private void stopTomcat() {
+		if (tomcat != null) {
+			try {
+				tomcat.stop();
+				tomcat.destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
similarity index 97%
rename from mcp/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
rename to mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
index 8d75b8479..42747f717 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
@@ -48,7 +48,7 @@
  * @author Daniel Garnier-Moiroux
  */
 @Timeout(15)
-public class McpTransportContextIntegrationTests {
+public class SyncServerMcpTransportContextIntegrationTests {
 
 	private static final int PORT = TomcatTestUtil.findAvailablePort();
 
@@ -135,6 +135,12 @@ public void after() {
 		if (sseServerTransport != null) {
 			sseServerTransport.closeGracefully().block();
 		}
+		if (streamableClient != null) {
+			streamableClient.closeGracefully();
+		}
+		if (sseClient != null) {
+			sseClient.closeGracefully();
+		}
 		stopTomcat();
 	}
 

From 4d779e139cc49817073b51a62a0f7b58c3767f3e Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Thu, 4 Sep 2025 12:55:26 +0200
Subject: [PATCH 061/125] Fix flakey test in
 HttpClientStreamableHttpTransportErrorHandlingTest (#535)

---
 .../HttpClientStreamableHttpTransportErrorHandlingTest.java     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
index 2b502a83b..b82d6eb2c 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
@@ -63,7 +63,7 @@ void startServer() throws IOException {
 			if ("DELETE".equals(httpExchange.getRequestMethod())) {
 				httpExchange.sendResponseHeaders(200, 0);
 			}
-			else {
+			else if ("POST".equals(httpExchange.getRequestMethod())) {
 				// Capture session ID from request if present
 				String requestSessionId = httpExchange.getRequestHeaders().getFirst(HttpHeaders.MCP_SESSION_ID);
 				lastReceivedSessionId.set(requestSessionId);

From ec4b32969905cdc9128752556722136b1562c9e0 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Thu, 4 Sep 2025 14:46:08 +0200
Subject: [PATCH 062/125] test: upgrade mcp-everything-server to v3 and fix
 resiliency test race condition (#536)

- Upgrade Docker test server image from v2 to v3 across all test files
- Updates all test files to use the latest version of the mcp-everything-server
Docker image (v3) for integration testing.
- Fix race condition in async client tests by not advertising roots capability during initialization
  - Prevents server from listing roots during init which could cause timing issues when disconnecting immediately after initialization
- Applied fix to AbstractMcpAsyncClientResiliencyTests (both mcp and mcp-test modules) and HttpSseMcpAsyncClientLostConnectionTests

Signed-off-by: Christian Tzolov 
Co-authored-by: Daniel Garnier-Moiroux 
---
 .../client/WebClientStreamableHttpAsyncClientTests.java  | 2 +-
 .../client/WebClientStreamableHttpSyncClientTests.java   | 2 +-
 .../client/WebFluxSseMcpAsyncClientTests.java            | 2 +-
 .../client/WebFluxSseMcpSyncClientTests.java             | 2 +-
 ...ebClientStreamableHttpTransportErrorHandlingTest.java | 1 -
 .../client/transport/WebFluxSseClientTransportTests.java | 2 +-
 .../client/AbstractMcpAsyncClientResiliencyTests.java    | 8 ++++++--
 .../client/AbstractMcpAsyncClientResiliencyTests.java    | 8 ++++++--
 .../client/HttpClientStreamableHttpAsyncClientTests.java | 2 +-
 .../client/HttpClientStreamableHttpSyncClientTests.java  | 2 +-
 .../client/HttpSseMcpAsyncClientLostConnectionTests.java | 9 ++++++---
 .../client/HttpSseMcpAsyncClientTests.java               | 2 +-
 .../client/HttpSseMcpSyncClientTests.java                | 2 +-
 .../transport/HttpClientSseClientTransportTests.java     | 2 +-
 .../transport/HttpClientStreamableHttpTransportTest.java | 2 +-
 15 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
index 8ef8177eb..1a4eedd15 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
@@ -21,7 +21,7 @@ public class WebClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncCli
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
index 1b252e27b..16f1d79a6 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
@@ -21,7 +21,7 @@ public class WebClientStreamableHttpSyncClientTests extends AbstractMcpSyncClien
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
index e32222357..0a92beac4 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
@@ -28,7 +28,7 @@ class WebFluxSseMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
index a62dea267..804feb135 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
@@ -28,7 +28,7 @@ class WebFluxSseMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java
index cdbb97e17..214fa489b 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportErrorHandlingTest.java
@@ -20,7 +20,6 @@
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Timeout;
 import org.springframework.web.reactive.function.client.WebClient;
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
index 53f54d121..06c95d145 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
@@ -44,7 +44,7 @@ class WebFluxSseClientTransportTests {
 	static String host = "http://localhost:3001";
 
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index ed34ebff6..d1f316094 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -10,6 +10,7 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpTransport;
+import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -48,7 +49,7 @@ public abstract class AbstractMcpAsyncClientResiliencyTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withNetwork(network)
@@ -134,10 +135,13 @@ McpAsyncClient client(McpClientTransport transport, Function client = new AtomicReference<>();
 
 		assertThatCode(() -> {
+			// Do not advertise roots. Otherwise, the server will list roots during
+			// initialization. The client responds asynchronously, and there might be a
+			// rest condition in tests where we disconnect right after initialization.
 			McpClient.AsyncSpec builder = McpClient.async(transport)
 				.requestTimeout(getRequestTimeout())
 				.initializationTimeout(getInitializationTimeout())
-				.capabilities(McpSchema.ClientCapabilities.builder().roots(true).build());
+				.capabilities(McpSchema.ClientCapabilities.builder().build());
 			builder = customizer.apply(builder);
 			client.set(builder.build());
 		}).doesNotThrowAnyException();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index ec23e21dc..3dbd413af 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -10,6 +10,7 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpTransport;
+import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -49,7 +50,7 @@ public abstract class AbstractMcpAsyncClientResiliencyTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withNetwork(network)
@@ -135,10 +136,13 @@ McpAsyncClient client(McpClientTransport transport, Function client = new AtomicReference<>();
 
 		assertThatCode(() -> {
+			// Do not advertise roots. Otherwise, the server will list roots during
+			// initialization. The client responds asynchronously, and there might be a
+			// rest condition in tests where we disconnect right after initialization.
 			McpClient.AsyncSpec builder = McpClient.async(transport)
 				.requestTimeout(getRequestTimeout())
 				.initializationTimeout(getInitializationTimeout())
-				.capabilities(McpSchema.ClientCapabilities.builder().roots(true).build());
+				.capabilities(McpSchema.ClientCapabilities.builder().build());
 			builder = customizer.apply(builder);
 			client.set(builder.build());
 		}).doesNotThrowAnyException();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
index 647e27d30..89848c549 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
@@ -20,7 +20,7 @@ public class HttpClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncCl
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
index e798db82e..d59ae35b4 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
@@ -32,7 +32,7 @@ public class HttpClientStreamableHttpSyncClientTests extends AbstractMcpSyncClie
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
index 0a72b785d..ba740518b 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
@@ -28,7 +28,7 @@
 import io.modelcontextprotocol.spec.McpSchema;
 import reactor.test.StepVerifier;
 
-@Timeout(15)
+@Timeout(20)
 public class HttpSseMcpAsyncClientLostConnectionTests {
 
 	private static final Logger logger = LoggerFactory.getLogger(HttpSseMcpAsyncClientLostConnectionTests.class);
@@ -38,7 +38,7 @@ public class HttpSseMcpAsyncClientLostConnectionTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withNetwork(network)
@@ -98,10 +98,13 @@ McpAsyncClient client(McpClientTransport transport) {
 		AtomicReference client = new AtomicReference<>();
 
 		assertThatCode(() -> {
+			// Do not advertise roots. Otherwise, the server will list roots during
+			// initialization. The client responds asynchronously, and there might be a
+			// rest condition in tests where we disconnect right after initialization.
 			McpClient.AsyncSpec builder = McpClient.async(transport)
 				.requestTimeout(Duration.ofSeconds(14))
 				.initializationTimeout(Duration.ofSeconds(2))
-				.capabilities(McpSchema.ClientCapabilities.builder().roots(true).build());
+				.capabilities(McpSchema.ClientCapabilities.builder().build());
 			client.set(builder.build());
 		}).doesNotThrowAnyException();
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
index 8827f7ec7..f467289ff 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
@@ -25,7 +25,7 @@ class HttpSseMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
index 38c6fdc4e..483d38669 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
@@ -38,7 +38,7 @@ class HttpSseMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
 	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
index 257d65f06..e088b8773 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
@@ -59,7 +59,7 @@ class HttpClientSseClientTransportTests {
 	static String host = "http://localhost:3001";
 
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index 670e6c7e6..398b1540b 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -41,7 +41,7 @@ class HttpClientStreamableHttpTransportTest {
 		.create(Map.of("test-transport-context-key", "some-value"));
 
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v2")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
 		.withCommand("node dist/index.js streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)

From 23142384694ee8c783a2d94164472b7bc03c5c3b Mon Sep 17 00:00:00 2001
From: Richie Caputo 
Date: Mon, 1 Sep 2025 12:21:48 -0400
Subject: [PATCH 063/125] fix: filter template resources from standard resource
 listing (#528)

- Add filter to exclude resources with template parameters ({}) from resources/list
- Template resources should only appear in resources/templates/list per MCP spec
- Add comprehensive test coverage for resource/template separation
- Update mock transport utilities for better test support

Signed-off-by: Christian Tzolov 
---
 .../server/McpAsyncServer.java                |   3 +-
 .../MockMcpServerTransport.java               |   8 ++
 .../server/ResourceTemplateListingTest.java   | 100 ++++++++++++++++++
 3 files changed, 110 insertions(+), 1 deletion(-)
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java

diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index a51c2e36c..dc81e65a8 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -594,6 +594,7 @@ private McpRequestHandler resourcesListRequestHan
 			var resourceList = this.resources.values()
 				.stream()
 				.map(McpServerFeatures.AsyncResourceSpecification::resource)
+				.filter(resource -> !resource.uri().contains("{"))
 				.toList();
 			return Mono.just(new McpSchema.ListResourcesResult(resourceList, null));
 		};
@@ -906,4 +907,4 @@ void setProtocolVersions(List protocolVersions) {
 		this.protocolVersions = protocolVersions;
 	}
 
-}
+}
\ No newline at end of file
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java b/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
index 4be680e11..778746faa 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
@@ -53,6 +53,14 @@ public McpSchema.JSONRPCMessage getLastSentMessage() {
 		return !sent.isEmpty() ? sent.get(sent.size() - 1) : null;
 	}
 
+	public void clearSentMessages() {
+		sent.clear();
+	}
+
+	public List getAllSentMessages() {
+		return new ArrayList<>(sent);
+	}
+
 	@Override
 	public Mono closeGracefully() {
 		return Mono.empty();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java b/mcp/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java
new file mode 100644
index 000000000..61703c306
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java
@@ -0,0 +1,100 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Test to verify the separation of regular resources and resource templates. Regular
+ * resources (without template parameters) should only appear in resources/list. Template
+ * resources (containing {}) should only appear in resources/templates/list.
+ */
+public class ResourceTemplateListingTest {
+
+	@Test
+	void testTemplateResourcesFilteredFromRegularListing() {
+		// The change we made filters resources containing "{" from the regular listing
+		// This test verifies that behavior is working correctly
+
+		// Given a string with template parameter
+		String templateUri = "file:///test/{userId}/profile.txt";
+		assertThat(templateUri.contains("{")).isTrue();
+
+		// And a regular URI
+		String regularUri = "file:///test/regular.txt";
+		assertThat(regularUri.contains("{")).isFalse();
+
+		// The filter should exclude template URIs
+		assertThat(!templateUri.contains("{")).isFalse();
+		assertThat(!regularUri.contains("{")).isTrue();
+	}
+
+	@Test
+	void testResourceListingWithMixedResources() {
+		// Create resource list with both regular and template resources
+		List allResources = List.of(
+				new McpSchema.Resource("file:///test/doc1.txt", "Document 1", "text/plain", null, null),
+				new McpSchema.Resource("file:///test/doc2.txt", "Document 2", "text/plain", null, null),
+				new McpSchema.Resource("file:///test/{type}/document.txt", "Typed Document", "text/plain", null, null),
+				new McpSchema.Resource("file:///users/{userId}/files/{fileId}", "User File", "text/plain", null, null));
+
+		// Apply the filter logic from McpAsyncServer line 438
+		List filteredResources = allResources.stream()
+			.filter(resource -> !resource.uri().contains("{"))
+			.collect(Collectors.toList());
+
+		// Verify only regular resources are included
+		assertThat(filteredResources).hasSize(2);
+		assertThat(filteredResources).extracting(McpSchema.Resource::uri)
+			.containsExactlyInAnyOrder("file:///test/doc1.txt", "file:///test/doc2.txt");
+	}
+
+	@Test
+	void testResourceTemplatesListedSeparately() {
+		// Create mixed resources
+		List resources = List.of(
+				new McpSchema.Resource("file:///test/regular.txt", "Regular Resource", "text/plain", null, null),
+				new McpSchema.Resource("file:///test/user/{userId}/profile.txt", "User Profile", "text/plain", null,
+						null));
+
+		// Create explicit resource template
+		McpSchema.ResourceTemplate explicitTemplate = new McpSchema.ResourceTemplate(
+				"file:///test/document/{docId}/content.txt", "Document Template", null, "text/plain", null);
+
+		// Filter regular resources (those without template parameters)
+		List regularResources = resources.stream()
+			.filter(resource -> !resource.uri().contains("{"))
+			.collect(Collectors.toList());
+
+		// Extract template resources (those with template parameters)
+		List templateResources = resources.stream()
+			.filter(resource -> resource.uri().contains("{"))
+			.map(resource -> new McpSchema.ResourceTemplate(resource.uri(), resource.name(), resource.description(),
+					resource.mimeType(), resource.annotations()))
+			.collect(Collectors.toList());
+
+		// Verify regular resources list
+		assertThat(regularResources).hasSize(1);
+		assertThat(regularResources.get(0).uri()).isEqualTo("file:///test/regular.txt");
+
+		// Verify template resources list includes both extracted and explicit templates
+		assertThat(templateResources).hasSize(1);
+		assertThat(templateResources.get(0).uriTemplate()).isEqualTo("file:///test/user/{userId}/profile.txt");
+
+		// In the actual implementation, both would be combined
+		List allTemplates = List.of(templateResources.get(0), explicitTemplate);
+		assertThat(allTemplates).hasSize(2);
+		assertThat(allTemplates).extracting(McpSchema.ResourceTemplate::uriTemplate)
+			.containsExactlyInAnyOrder("file:///test/user/{userId}/profile.txt",
+					"file:///test/document/{docId}/content.txt");
+	}
+
+}
\ No newline at end of file

From 681fe7f90b12191ba18dacaffa5635d68c65a9c0 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Thu, 4 Sep 2025 16:52:21 +0200
Subject: [PATCH 064/125] test: ensure proper resource cleanup in integration
 tests (#537)

- Add try-finally blocks to guarantee server cleanup on test completion
- Call closeGracefully().block() to ensure synchronous shutdown
- Use try-with-resources for client lifecycle management where applicable
- Prevent resource leaks and potential test flakiness

Signed-off-by: Christian Tzolov 
---
 ...stractMcpClientServerIntegrationTests.java | 237 +++++++++--------
 .../AbstractStatelessIntegrationTests.java    |  44 ++--
 ...stractMcpClientServerIntegrationTests.java | 239 ++++++++++--------
 .../HttpServletStatelessIntegrationTests.java |  35 ++-
 4 files changed, 317 insertions(+), 238 deletions(-)

diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 300f0b534..c0e2509c9 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -91,7 +91,9 @@ void simple(String clientType) {
 			assertThat(client.initialize()).isNotNull();
 
 		}
-		server.closeGracefully();
+		finally {
+			server.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -128,7 +130,9 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 					.hasMessage("Client must be configured with sampling capabilities");
 			}
 		}
-		server.closeGracefully();
+		finally {
+			server.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -195,7 +199,9 @@ void testCreateMessageSuccess(String clientType) {
 				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
 			});
 		}
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -219,11 +225,6 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
 		// Server
 
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
@@ -256,26 +257,31 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 			.requestTimeout(Duration.ofSeconds(4))
 			.tools(tool)
 			.build();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
 
-		assertWith(samplingResult.get(), result -> {
-			assertThat(result).isNotNull();
-			assertThat(result.role()).isEqualTo(Role.USER);
-			assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-			assertThat(result.model()).isEqualTo("MockModelName");
-			assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-		});
-
-		mcpClient.close();
-		mcpServer.close();
+			assertWith(samplingResult.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.role()).isEqualTo(Role.USER);
+				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+				assertThat(result.model()).isEqualTo("MockModelName");
+				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+			});
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -297,11 +303,6 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
@@ -329,15 +330,21 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 			.tools(tool)
 			.build();
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
 
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("1000ms");
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		mcpClient.close();
-		mcpServer.close();
+			assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}).withMessageContaining("1000ms");
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -370,7 +377,9 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 					.hasMessage("Client must be configured with elicitation capabilities");
 			}
 		}
-		server.closeGracefully().block();
+		finally {
+			server.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -425,7 +434,9 @@ void testCreateElicitationSuccess(String clientType) {
 			assertThat(response).isNotNull();
 			assertThat(response).isEqualTo(callResponse);
 		}
-		mcpServer.closeGracefully().block();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -440,11 +451,6 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
@@ -471,21 +477,27 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 			.tools(tool)
 			.build();
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build()) {
 
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-		assertWith(resultRef.get(), result -> {
-			assertThat(result).isNotNull();
-			assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
-			assertThat(result.content().get("message")).isEqualTo("Test message");
-		});
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+			assertWith(resultRef.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+				assertThat(result.content().get("message")).isEqualTo("Test message");
+			});
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -511,11 +523,6 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
 		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 
 		AtomicReference resultRef = new AtomicReference<>();
@@ -541,18 +548,24 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 			.tools(tool)
 			.build();
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build()) {
 
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("within 1000ms");
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		ElicitResult elicitResult = resultRef.get();
-		assertThat(elicitResult).isNull();
+			assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}).withMessageContaining("within 1000ms");
 
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
+			ElicitResult elicitResult = resultRef.get();
+			assertThat(elicitResult).isNull();
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -601,8 +614,9 @@ void testRootsSuccess(String clientType) {
 				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -639,8 +653,9 @@ void testRootsWithoutCapability(String clientType) {
 				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
 			}
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -668,8 +683,9 @@ void testRootsNotificationWithEmptyRootsList(String clientType) {
 				assertThat(rootsRef.get()).isEmpty();
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -701,8 +717,9 @@ void testRootsWithMultipleHandlers(String clientType) {
 				assertThat(rootsRef2.get()).containsAll(roots);
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -732,8 +749,9 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 				assertThat(rootsRef.get()).containsAll(roots);
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	// ---------------------------------------
@@ -793,8 +811,9 @@ void testToolCallSuccess(String clientType) {
 			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
 			assertThat(response).isNotNull().isEqualTo(callResponse);
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -830,8 +849,9 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
 				.withMessageContaining("Timeout on blocking read");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -886,8 +906,9 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
 			assertThat(response).isNotNull().isEqualTo(expectedCallResponse);
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -978,8 +999,9 @@ void testToolListChangeHandlingSuccess(String clientType) {
 				assertThat(toolsRef.get()).containsAll(List.of(tool2.tool()));
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -995,8 +1017,9 @@ void testInitialize(String clientType) {
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	// ---------------------------------------
@@ -1107,7 +1130,9 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 			assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
 			assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
 		}
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -1212,7 +1237,7 @@ void testProgressNotification(String clientType) throws InterruptedException {
 			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
 		}
 		finally {
-			mcpServer.close();
+			mcpServer.closeGracefully().block();
 		}
 	}
 
@@ -1262,8 +1287,9 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
 			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	// ---------------------------------------
@@ -1324,8 +1350,9 @@ void testPingSuccess(String clientType) {
 			// Verify execution order
 			assertThat(executionOrder.get()).isEqualTo("123");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -1400,8 +1427,9 @@ void testStructuredOutputValidationSuccess(String clientType) {
 				.isEqualTo(json("""
 						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -1454,8 +1482,9 @@ void testStructuredOutputValidationFailure(String clientType) {
 			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
 			assertThat(errorMessage).contains("Validation failed");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -1504,8 +1533,9 @@ void testStructuredOutputMissingStructuredContent(String clientType) {
 			assertThat(errorMessage).isEqualTo(
 					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -1581,8 +1611,9 @@ void testStructuredOutputRuntimeToolAddition(String clientType) {
 				.isEqualTo(json("""
 						{"count":3,"message":"Dynamic execution"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	private double evaluateExpression(String expression) {
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
index 618247d61..777e12a9c 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
@@ -66,7 +66,9 @@ void simple(String clientType) {
 			assertThat(client.initialize()).isNotNull();
 
 		}
-		server.closeGracefully();
+		finally {
+			server.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -126,8 +128,9 @@ void testToolCallSuccess(String clientType) {
 
 			assertThat(response).isNotNull().isEqualTo(callResponse);
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -163,8 +166,9 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
 				.withMessageContaining("Timeout on blocking read");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -244,8 +248,9 @@ void testToolListChangeHandlingSuccess(String clientType) {
 
 			mcpServer.addTool(tool2);
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -261,8 +266,9 @@ void testInitialize(String clientType) {
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	// ---------------------------------------
@@ -339,8 +345,9 @@ void testStructuredOutputValidationSuccess(String clientType) {
 				.isEqualTo(json("""
 						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -394,8 +401,9 @@ void testStructuredOutputValidationFailure(String clientType) {
 			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
 			assertThat(errorMessage).contains("Validation failed");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -444,8 +452,9 @@ void testStructuredOutputMissingStructuredContent(String clientType) {
 			assertThat(errorMessage).isEqualTo(
 					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -521,8 +530,9 @@ void testStructuredOutputRuntimeToolAddition(String clientType) {
 				.isEqualTo(json("""
 						{"count":3,"message":"Dynamic execution"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	private double evaluateExpression(String expression) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index f99edaf95..2e1a12a95 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -87,7 +87,9 @@ void simple(String clientType) {
 			assertThat(client.initialize()).isNotNull();
 
 		}
-		server.closeGracefully();
+		finally {
+			server.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -124,7 +126,9 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 					.hasMessage("Client must be configured with sampling capabilities");
 			}
 		}
-		server.closeGracefully();
+		finally {
+			server.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -191,7 +195,9 @@ void testCreateMessageSuccess(String clientType) {
 				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
 			});
 		}
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -215,11 +221,6 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
 		// Server
 
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
@@ -252,26 +253,31 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 			.requestTimeout(Duration.ofSeconds(4))
 			.tools(tool)
 			.build();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
 
-		assertWith(samplingResult.get(), result -> {
-			assertThat(result).isNotNull();
-			assertThat(result.role()).isEqualTo(Role.USER);
-			assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
-			assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
-			assertThat(result.model()).isEqualTo("MockModelName");
-			assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
-		});
-
-		mcpClient.close();
-		mcpServer.close();
+			assertWith(samplingResult.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.role()).isEqualTo(Role.USER);
+				assertThat(result.content()).isInstanceOf(McpSchema.TextContent.class);
+				assertThat(((McpSchema.TextContent) result.content()).text()).isEqualTo("Test message");
+				assertThat(result.model()).isEqualTo("MockModelName");
+				assertThat(result.stopReason()).isEqualTo(CreateMessageResult.StopReason.STOP_SEQUENCE);
+			});
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -293,11 +299,6 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().sampling().build())
-			.sampling(samplingHandler)
-			.build();
-
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
@@ -325,15 +326,21 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 			.tools(tool)
 			.build();
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().sampling().build())
+			.sampling(samplingHandler)
+			.build()) {
 
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("1000ms");
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		mcpClient.close();
-		mcpServer.close();
+			assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}).withMessageContaining("1000ms");
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -366,7 +373,9 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 					.hasMessage("Client must be configured with elicitation capabilities");
 			}
 		}
-		server.closeGracefully().block();
+		finally {
+			server.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -421,7 +430,9 @@ void testCreateElicitationSuccess(String clientType) {
 			assertThat(response).isNotNull();
 			assertThat(response).isEqualTo(callResponse);
 		}
-		mcpServer.closeGracefully().block();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -436,11 +447,6 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
 		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
 				null);
 
@@ -467,21 +473,27 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 			.tools(tool)
 			.build();
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build()) {
 
-		CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		assertThat(response).isNotNull();
-		assertThat(response).isEqualTo(callResponse);
-		assertWith(resultRef.get(), result -> {
-			assertThat(result).isNotNull();
-			assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
-			assertThat(result.content().get("message")).isEqualTo("Test message");
-		});
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
 
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
+			assertThat(response).isNotNull();
+			assertThat(response).isEqualTo(callResponse);
+			assertWith(resultRef.get(), result -> {
+				assertThat(result).isNotNull();
+				assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
+				assertThat(result.content().get("message")).isEqualTo("Test message");
+			});
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -507,11 +519,6 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
-			.capabilities(ClientCapabilities.builder().elicitation().build())
-			.elicitation(elicitationHandler)
-			.build();
-
 		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 
 		AtomicReference resultRef = new AtomicReference<>();
@@ -537,18 +544,24 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 			.tools(tool)
 			.build();
 
-		InitializeResult initResult = mcpClient.initialize();
-		assertThat(initResult).isNotNull();
+		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample client", "0.0.0"))
+			.capabilities(ClientCapabilities.builder().elicitation().build())
+			.elicitation(elicitationHandler)
+			.build()) {
 
-		assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
-			mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
-		}).withMessageContaining("within 1000ms");
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
 
-		ElicitResult elicitResult = resultRef.get();
-		assertThat(elicitResult).isNull();
+			assertThatExceptionOfType(McpError.class).isThrownBy(() -> {
+				mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of()));
+			}).withMessageContaining("within 1000ms");
 
-		mcpClient.closeGracefully();
-		mcpServer.closeGracefully().block();
+			ElicitResult elicitResult = resultRef.get();
+			assertThat(elicitResult).isNull();
+		}
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -597,8 +610,9 @@ void testRootsSuccess(String clientType) {
 				assertThat(rootsRef.get()).containsAll(List.of(roots.get(1), root3));
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -635,8 +649,9 @@ void testRootsWithoutCapability(String clientType) {
 				assertThat(e).isInstanceOf(McpError.class).hasMessage("Roots not supported");
 			}
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -664,8 +679,9 @@ void testRootsNotificationWithEmptyRootsList(String clientType) {
 				assertThat(rootsRef.get()).isEmpty();
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -697,8 +713,9 @@ void testRootsWithMultipleHandlers(String clientType) {
 				assertThat(rootsRef2.get()).containsAll(roots);
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -728,8 +745,9 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 				assertThat(rootsRef.get()).containsAll(roots);
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	// ---------------------------------------
@@ -789,8 +807,9 @@ void testToolCallSuccess(String clientType) {
 			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
 			assertThat(response).isNotNull().isEqualTo(callResponse);
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -826,8 +845,9 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
 				.withMessageContaining("Timeout on blocking read");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -882,8 +902,9 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 			assertThat(responseBodyIsNullOrBlank.get()).isFalse();
 			assertThat(response).isNotNull().isEqualTo(expectedCallResponse);
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -974,8 +995,9 @@ void testToolListChangeHandlingSuccess(String clientType) {
 				assertThat(toolsRef.get()).containsAll(List.of(tool2.tool()));
 			});
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -991,8 +1013,9 @@ void testInitialize(String clientType) {
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	// ---------------------------------------
@@ -1056,7 +1079,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 			.build();
 
 		var mcpServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
-			.capabilities(ServerCapabilities.builder().logging().tools(true).build())
+			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(tool)
 			.build();
 
@@ -1103,7 +1126,9 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 			assertThat(notificationMap.get("Another error message").logger()).isEqualTo("test-logger");
 			assertThat(notificationMap.get("Another error message").data()).isEqualTo("Another error message");
 		}
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -1208,7 +1233,7 @@ void testProgressNotification(String clientType) throws InterruptedException {
 			assertThat(notificationMap.get("Processing completed").message()).isEqualTo("Processing completed");
 		}
 		finally {
-			mcpServer.close();
+			mcpServer.closeGracefully().block();
 		}
 	}
 
@@ -1258,8 +1283,9 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
 			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	// ---------------------------------------
@@ -1320,8 +1346,9 @@ void testPingSuccess(String clientType) {
 			// Verify execution order
 			assertThat(executionOrder.get()).isEqualTo("123");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully().block();
+		}
 	}
 
 	// ---------------------------------------
@@ -1396,8 +1423,9 @@ void testStructuredOutputValidationSuccess(String clientType) {
 				.isEqualTo(json("""
 						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -1450,8 +1478,9 @@ void testStructuredOutputValidationFailure(String clientType) {
 			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
 			assertThat(errorMessage).contains("Validation failed");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -1500,8 +1529,9 @@ void testStructuredOutputMissingStructuredContent(String clientType) {
 			assertThat(errorMessage).isEqualTo(
 					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -1577,8 +1607,9 @@ void testStructuredOutputRuntimeToolAddition(String clientType) {
 				.isEqualTo(json("""
 						{"count":3,"message":"Dynamic execution"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.closeGracefully();
+		}
 	}
 
 	private double evaluateExpression(String expression) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index 6a6f6f8b9..bb405b728 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -151,8 +151,9 @@ void testToolCallSuccess(String clientType) {
 			assertThat(response).isNotNull();
 			assertThat(response).isEqualTo(callResponse);
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.close();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -167,8 +168,9 @@ void testInitialize(String clientType) {
 			InitializeResult initResult = mcpClient.initialize();
 			assertThat(initResult).isNotNull();
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.close();
+		}
 	}
 
 	// ---------------------------------------
@@ -218,8 +220,9 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
 			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.close();
+		}
 	}
 
 	// ---------------------------------------
@@ -290,8 +293,9 @@ void testStructuredOutputValidationSuccess(String clientType) {
 				.isEqualTo(json("""
 						{"result":5.0,"operation":"2 + 3","timestamp":"2024-01-01T10:00:00Z"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.close();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -342,8 +346,9 @@ void testStructuredOutputValidationFailure(String clientType) {
 			String errorMessage = ((McpSchema.TextContent) response.content().get(0)).text();
 			assertThat(errorMessage).contains("Validation failed");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.close();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -391,8 +396,9 @@ void testStructuredOutputMissingStructuredContent(String clientType) {
 			assertThat(errorMessage).isEqualTo(
 					"Response missing structured content which is expected when calling tool with non-empty outputSchema");
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.close();
+		}
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
@@ -465,8 +471,9 @@ void testStructuredOutputRuntimeToolAddition(String clientType) {
 				.isEqualTo(json("""
 						{"count":3,"message":"Dynamic execution"}"""));
 		}
-
-		mcpServer.close();
+		finally {
+			mcpServer.close();
+		}
 	}
 
 	@Test

From 7cf5907da411d9163e8c10432dbc8fc30c1594a1 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 4 Sep 2025 22:33:14 +0200
Subject: [PATCH 065/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       | 2 +-
 mcp-spring/mcp-spring-webflux/pom.xml | 6 +++---
 mcp-spring/mcp-spring-webmvc/pom.xml  | 8 ++++----
 mcp-test/pom.xml                      | 4 ++--
 mcp/pom.xml                           | 2 +-
 pom.xml                               | 2 +-
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 83d8bc510..ac68e55bc 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.12.0-SNAPSHOT
+        0.13.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 300d518e7..c2dac2bf9 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.12.0-SNAPSHOT
+		0.13.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.12.0-SNAPSHOT
+			0.13.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.12.0-SNAPSHOT
+			0.13.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 170309211..4bd9f87aa 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.12.0-SNAPSHOT
+		0.13.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,7 +25,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.12.0-SNAPSHOT
+			0.13.0-SNAPSHOT
 		
 
 		
@@ -37,14 +37,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.12.0-SNAPSHOT
+			0.13.0-SNAPSHOT
 			test
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.12.0-SNAPSHOT
+			0.13.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 563f60de9..5b77d0acb 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.12.0-SNAPSHOT
+		0.13.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.12.0-SNAPSHOT
+			0.13.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 1cf61c48f..dc85a419e 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.12.0-SNAPSHOT
+		0.13.0-SNAPSHOT
 	
 	mcp
 	jar
diff --git a/pom.xml b/pom.xml
index c0b1f7a44..9990a4663 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.12.0-SNAPSHOT
+	0.13.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From d8cc189341497b34d8932f18c8a28ab3b8e3213c Mon Sep 17 00:00:00 2001
From: Yanming Zhou 
Date: Thu, 21 Aug 2025 17:10:33 +0800
Subject: [PATCH 066/125] fix: Add null check for response ID to prevent memory
 leaks

- Check if response.id() is not null before processing in MCP session classes
- Log error when MCP response lacks session ID to warn about potential memory leaks
- Improve error handling in McpStreamableServerSession with proper error codes

The missing null check could lead to memory leaks as pending requests
would never be completed when responses lack session IDs. This fix ensures
proper handling of such cases with appropriate error logging.

Resolves #506

Signed-off-by: Yanming Zhou 
---
 .../spec/McpClientSession.java                | 18 +++++++---
 .../spec/McpServerSession.java                | 17 ++++++---
 .../spec/McpStreamableServerSession.java      | 35 +++++++++++++------
 3 files changed, 49 insertions(+), 21 deletions(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
index f7db3d7aa..6ac8defa0 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
@@ -35,6 +35,7 @@
  *
  * @author Christian Tzolov
  * @author Dariusz Jędrzejczyk
+ * @author Yanming Zhou
  */
 public class McpClientSession implements McpSession {
 
@@ -146,13 +147,20 @@ private void dismissPendingResponses() {
 
 	private void handle(McpSchema.JSONRPCMessage message) {
 		if (message instanceof McpSchema.JSONRPCResponse response) {
-			logger.debug("Received Response: {}", response);
-			var sink = pendingResponses.remove(response.id());
-			if (sink == null) {
-				logger.warn("Unexpected response for unknown id {}", response.id());
+			logger.debug("Received response: {}", response);
+			if (response.id() != null) {
+				var sink = pendingResponses.remove(response.id());
+				if (sink == null) {
+					logger.warn("Unexpected response for unknown id {}", response.id());
+				}
+				else {
+					sink.success(response);
+				}
 			}
 			else {
-				sink.success(response);
+				logger.error("Discarded MCP request response without session id. "
+						+ "This is an indication of a bug in the request sender code that can lead to memory "
+						+ "leaks as pending requests will never be completed.");
 			}
 		}
 		else if (message instanceof McpSchema.JSONRPCRequest request) {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index e6a0c8b32..747b45490 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -204,13 +204,20 @@ public Mono handle(McpSchema.JSONRPCMessage message) {
 			// TODO handle errors for communication to without initialization happening
 			// first
 			if (message instanceof McpSchema.JSONRPCResponse response) {
-				logger.debug("Received Response: {}", response);
-				var sink = pendingResponses.remove(response.id());
-				if (sink == null) {
-					logger.warn("Unexpected response for unknown id {}", response.id());
+				logger.debug("Received response: {}", response);
+				if (response.id() != null) {
+					var sink = pendingResponses.remove(response.id());
+					if (sink == null) {
+						logger.warn("Unexpected response for unknown id {}", response.id());
+					}
+					else {
+						sink.success(response);
+					}
 				}
 				else {
-					sink.success(response);
+					logger.error("Discarded MCP request response without session id. "
+							+ "This is an indication of a bug in the request sender code that can lead to memory "
+							+ "leaks as pending requests will never be completed.");
 				}
 				return Mono.empty();
 			}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
index af29ce0ad..53b56c70f 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -21,6 +21,7 @@
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
 import io.modelcontextprotocol.server.McpNotificationHandler;
 import io.modelcontextprotocol.server.McpRequestHandler;
+import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
 import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
@@ -33,6 +34,7 @@
  * capability without the insight into the transport-specific details of HTTP handling.
  *
  * @author Dariusz Jędrzejczyk
+ * @author Yanming Zhou
  */
 public class McpStreamableServerSession implements McpLoggableSession {
 
@@ -214,19 +216,30 @@ public Mono accept(McpSchema.JSONRPCNotification notification) {
 	 */
 	public Mono accept(McpSchema.JSONRPCResponse response) {
 		return Mono.defer(() -> {
-			var stream = this.requestIdToStream.get(response.id());
-			if (stream == null) {
-				return Mono.error(new McpError("Unexpected response for unknown id " + response.id())); // TODO
-																										// JSONize
-			}
-			// TODO: encapsulate this inside the stream itself
-			var sink = stream.pendingResponses.remove(response.id());
-			if (sink == null) {
-				return Mono.error(new McpError("Unexpected response for unknown id " + response.id())); // TODO
-																										// JSONize
+			logger.debug("Received response: {}", response);
+
+			if (response.id() != null) {
+				var stream = this.requestIdToStream.get(response.id());
+				if (stream == null) {
+					return Mono.error(McpError.builder(ErrorCodes.INTERNAL_ERROR)
+						.message("Unexpected response for unknown id " + response.id())
+						.build());
+				}
+				// TODO: encapsulate this inside the stream itself
+				var sink = stream.pendingResponses.remove(response.id());
+				if (sink == null) {
+					return Mono.error(McpError.builder(ErrorCodes.INTERNAL_ERROR)
+						.message("Unexpected response for unknown id " + response.id())
+						.build());
+				}
+				else {
+					sink.success(response);
+				}
 			}
 			else {
-				sink.success(response);
+				logger.error("Discarded MCP request response without session id. "
+						+ "This is an indication of a bug in the request sender code that can lead to memory "
+						+ "leaks as pending requests will never be completed.");
 			}
 			return Mono.empty();
 		});

From c7736b6ec6b1eef9da48826294bfa9ba3e7f77d1 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Sun, 7 Sep 2025 01:01:52 +0200
Subject: [PATCH 067/125] fix: Skip structured output validation for error tool
 results

This ensures that when a tool handler returns an error result, the structured
output schema validation is skipped, preventing validation failures on error
responses that don't conform to the expected output schema.

- Add validation bypass when CallToolResult.isError() is true in async/stateless servers
- Fix async tool handler chaining to properly use then() instead of block()
- Add comprehensive tests for structured output with in-handler errors
- Improve error handling to use proper JSON-RPC error codes for unknown tools
- Add findRootCause utility method for better error diagnostics
- Increase test timeouts for stability in StdioMcp client tests. These tests use npx
  to download and run the MCP "everything" server locally. The first
  test execution will download the everything server scripts and cache them locally,
  which can take more than 15 seconds. Subsequent test runs will use the cached version
  and execute faster.

Resolves #538
Related to #422

Signed-off-by: Christian Tzolov 
---
 ...stractMcpClientServerIntegrationTests.java | 86 +++++++++++++++---
 .../AbstractStatelessIntegrationTests.java    | 76 ++++++++++++++--
 .../server/McpAsyncServer.java                | 13 ++-
 .../server/McpStatelessAsyncServer.java       | 13 ++-
 .../io/modelcontextprotocol/util/Utils.java   |  4 +-
 .../client/StdioMcpAsyncClientTests.java      | 14 ++-
 .../client/StdioMcpSyncClientTests.java       | 14 ++-
 ...stractMcpClientServerIntegrationTests.java | 85 +++++++++++++++---
 .../HttpServletSseIntegrationTests.java       | 20 ++---
 .../HttpServletStatelessIntegrationTests.java | 88 ++++++++++++++++---
 ...HttpServletStreamableIntegrationTests.java | 20 ++---
 11 files changed, 353 insertions(+), 80 deletions(-)

diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index c0e2509c9..dd3bc59da 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -4,14 +4,6 @@
 
 package io.modelcontextprotocol;
 
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.assertj.core.api.Assertions.assertWith;
-import static org.awaitility.Awaitility.await;
-import static org.mockito.Mockito.mock;
-
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
@@ -29,9 +21,6 @@
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer;
@@ -56,12 +45,23 @@
 import io.modelcontextprotocol.spec.McpSchema.Role;
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.util.Utils;
 import net.javacrumbs.jsonunit.core.Option;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertWith;
+import static org.awaitility.Awaitility.await;
+import static org.mockito.Mockito.mock;
+
 public abstract class AbstractMcpClientServerIntegrationTests {
 
 	protected ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
@@ -108,8 +108,8 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
-				exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
-				return Mono.just(mock(CallToolResult.class));
+				return exchange.createMessage(mock(McpSchema.CreateMessageRequest.class))
+					.then(Mono.just(mock(CallToolResult.class)));
 			})
 			.build();
 
@@ -1434,6 +1434,66 @@ void testStructuredOutputValidationSuccess(String clientType) {
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputWithInHandlerError(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		// Handler that throws an exception to simulate an error
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+
+				return CallToolResult.builder()
+					.isError(true)
+					.content(List.of(new TextContent("Error calling tool: Simulated in-handler error")))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).isNotEmpty();
+			assertThat(response.content())
+				.containsExactly(new McpSchema.TextContent("Error calling tool: Simulated in-handler error"));
+			assertThat(response.structuredContent()).isNull();
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
 	void testStructuredOutputValidationFailure(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
index 777e12a9c..c96f10eda 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
@@ -4,12 +4,6 @@
 
 package io.modelcontextprotocol;
 
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.awaitility.Awaitility.await;
-
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
@@ -20,9 +14,6 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicReference;
 
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.server.McpServer.StatelessAsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.StatelessSyncSpecification;
@@ -33,10 +24,19 @@
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import net.javacrumbs.jsonunit.core.Option;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.awaitility.Awaitility.await;
+
 public abstract class AbstractStatelessIntegrationTests {
 
 	protected ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
@@ -350,6 +350,64 @@ void testStructuredOutputValidationSuccess(String clientType) {
 		}
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputWithInHandlerError(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		// Handler that throws an exception to simulate an error
+		McpStatelessServerFeatures.SyncToolSpecification tool = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> CallToolResult.builder()
+				.isError(true)
+				.content(List.of(new TextContent("Error calling tool: Simulated in-handler error")))
+				.build())
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).isNotEmpty();
+			assertThat(response.content())
+				.containsExactly(new McpSchema.TextContent("Error calling tool: Simulated in-handler error"));
+			assertThat(response.structuredContent()).isNull();
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testStructuredOutputValidationFailure(String clientType) {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index dc81e65a8..3c8057a72 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -29,10 +29,12 @@
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse;
 import io.modelcontextprotocol.spec.McpSchema.LoggingLevel;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
 import io.modelcontextprotocol.spec.McpSchema.SetLevelRequest;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
@@ -376,6 +378,11 @@ public Mono apply(McpAsyncServerExchange exchange, McpSchema.Cal
 
 			return this.delegateCallToolResult.apply(exchange, request).map(result -> {
 
+				if (Boolean.TRUE.equals(result.isError())) {
+					// If the tool call resulted in an error, skip further validation
+					return result;
+				}
+
 				if (outputSchema == null) {
 					if (result.structuredContent() != null) {
 						logger.warn(
@@ -507,11 +514,11 @@ private McpRequestHandler toolsCallRequestHandler() {
 				.findAny();
 
 			if (toolSpecification.isEmpty()) {
-				return Mono.error(new McpError("Tool not found: " + callToolRequest.name()));
+				return Mono.error(new McpError(new JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INVALID_PARAMS,
+						"Unknown tool: invalid_tool_name", "Tool not found: " + callToolRequest.name())));
 			}
 
-			return toolSpecification.map(tool -> Mono.defer(() -> tool.callHandler().apply(exchange, callToolRequest)))
-				.orElse(Mono.error(new McpError("Tool not found: " + callToolRequest.name())));
+			return toolSpecification.get().callHandler().apply(exchange, callToolRequest);
 		};
 	}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 451771295..50d45b14c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -11,7 +11,9 @@
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse;
 import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpStatelessServerTransport;
 import io.modelcontextprotocol.util.Assert;
@@ -249,6 +251,11 @@ public Mono apply(McpTransportContext transportContext, McpSchem
 
 			return this.delegateHandler.apply(transportContext, request).map(result -> {
 
+				if (Boolean.TRUE.equals(result.isError())) {
+					// If the tool call resulted in an error, skip further validation
+					return result;
+				}
+
 				if (outputSchema == null) {
 					if (result.structuredContent() != null) {
 						logger.warn(
@@ -375,11 +382,11 @@ private McpStatelessRequestHandler toolsCallRequestHandler() {
 				.findAny();
 
 			if (toolSpecification.isEmpty()) {
-				return Mono.error(new McpError("Tool not found: " + callToolRequest.name()));
+				return Mono.error(new McpError(new JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INVALID_PARAMS,
+						"Unknown tool: invalid_tool_name", "Tool not found: " + callToolRequest.name())));
 			}
 
-			return toolSpecification.map(tool -> tool.callHandler().apply(ctx, callToolRequest))
-				.orElse(Mono.error(new McpError("Tool not found: " + callToolRequest.name())));
+			return toolSpecification.get().callHandler().apply(ctx, callToolRequest);
 		};
 	}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java b/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java
index 039b0d68e..cd420100c 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java
@@ -4,12 +4,12 @@
 
 package io.modelcontextprotocol.util;
 
-import reactor.util.annotation.Nullable;
-
 import java.net.URI;
 import java.util.Collection;
 import java.util.Map;
 
+import reactor.util.annotation.Nullable;
+
 /**
  * Miscellaneous utility methods.
  *
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
index e9356d0c0..ef404c9ae 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
@@ -14,10 +14,17 @@
 /**
  * Tests for the {@link McpAsyncClient} with {@link StdioClientTransport}.
  *
+ * 

+ * These tests use npx to download and run the MCP "everything" server locally. The first
+ * test execution will download the everything server scripts and cache them locally,
+ * which can take more than 15 seconds. Subsequent test runs will use the cached version
+ * and execute faster.
+ *
  * @author Christian Tzolov
  * @author Dariusz Jędrzejczyk
  */
-@Timeout(15) // Giving extra time beyond the client timeout
+@Timeout(25) // Giving extra time beyond the client timeout to account for initial server
+				// download
 class StdioMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
 	@Override
@@ -40,4 +47,9 @@ protected Duration getInitializationTimeout() {
 		return Duration.ofSeconds(20);
 	}
 
+	@Override
+	protected Duration getRequestTimeout() {
+		return Duration.ofSeconds(25);
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
index 4b5f4f9c0..95c1e2947 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
@@ -22,10 +22,17 @@
 /**
  * Tests for the {@link McpSyncClient} with {@link StdioClientTransport}.
  *
+ * 

+ * These tests use npx to download and run the MCP "everything" server locally. The first
+ * test execution will download the everything server scripts and cache them locally,
+ * which can take more than 15 seconds. Subsequent test runs will use the cached version
+ * and execute faster.
+ *
  * @author Christian Tzolov
  * @author Dariusz Jędrzejczyk
  */
-@Timeout(15) // Giving extra time beyond the client timeout
+@Timeout(25) // Giving extra time beyond the client timeout to account for initial server
+				// download
 class StdioMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
 	@Override
@@ -71,4 +78,9 @@ protected Duration getInitializationTimeout() {
 		return Duration.ofSeconds(10);
 	}
 
+	@Override
+	protected Duration getRequestTimeout() {
+		return Duration.ofSeconds(25);
+	}
+
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index 2e1a12a95..8dae452f0 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -4,15 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
-import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
-import static org.assertj.core.api.Assertions.assertWith;
-import static org.awaitility.Awaitility.await;
-import static org.mockito.Mockito.mock;
-
-import io.modelcontextprotocol.common.McpTransportContext;
 import java.net.URI;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
@@ -30,10 +21,8 @@
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
-
 import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
@@ -52,12 +41,23 @@
 import io.modelcontextprotocol.spec.McpSchema.Role;
 import io.modelcontextprotocol.spec.McpSchema.Root;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.util.Utils;
 import net.javacrumbs.jsonunit.core.Option;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertWith;
+import static org.awaitility.Awaitility.await;
+import static org.mockito.Mockito.mock;
+
 public abstract class AbstractMcpClientServerIntegrationTests {
 
 	protected ConcurrentHashMap clientBuilders = new ConcurrentHashMap<>();
@@ -104,8 +104,8 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
 			.callHandler((exchange, request) -> {
-				exchange.createMessage(mock(McpSchema.CreateMessageRequest.class)).block();
-				return Mono.just(mock(CallToolResult.class));
+				return exchange.createMessage(mock(McpSchema.CreateMessageRequest.class))
+					.then(Mono.just(mock(CallToolResult.class)));
 			})
 			.build();
 
@@ -1428,6 +1428,63 @@ void testStructuredOutputValidationSuccess(String clientType) {
 		}
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputWithInHandlerError(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		// Handler that returns an error result
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> CallToolResult.builder()
+				.isError(true)
+				.content(List.of(new TextContent("Error calling tool: Simulated in-handler error")))
+				.build())
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).isNotEmpty();
+			assertThat(response.content())
+				.containsExactly(new McpSchema.TextContent("Error calling tool: Simulated in-handler error"));
+			assertThat(response.structuredContent()).isNull();
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testStructuredOutputValidationFailure(String clientType) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
index c893acf9a..8e618b9a8 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
@@ -4,28 +4,26 @@
 
 package io.modelcontextprotocol.server;
 
-import static org.assertj.core.api.Assertions.assertThat;
-
-import io.modelcontextprotocol.common.McpTransportContext;
 import java.time.Duration;
 import java.util.Map;
 
-import org.apache.catalina.LifecycleException;
-import org.apache.catalina.LifecycleState;
-import org.apache.catalina.startup.Tomcat;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Timeout;
-
 import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
 import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 import jakarta.servlet.http.HttpServletRequest;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
+
+import static org.assertj.core.api.Assertions.assertThat;
 
 @Timeout(15)
 class HttpServletSseIntegrationTests extends AbstractMcpClientServerIntegrationTests {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index bb405b728..5cc7d61be 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -4,6 +4,13 @@
 
 package io.modelcontextprotocol.server;
 
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
+
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
@@ -11,16 +18,17 @@
 import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 import io.modelcontextprotocol.spec.HttpHeaders;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
 import io.modelcontextprotocol.spec.McpSchema.CompleteResult;
+import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
 import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
 import io.modelcontextprotocol.spec.McpSchema.Prompt;
 import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
 import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.ProtocolVersions;
 import net.javacrumbs.jsonunit.core.Option;
@@ -33,17 +41,11 @@
 import org.junit.jupiter.api.Timeout;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
+
 import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.mock.web.MockHttpServletResponse;
 import org.springframework.web.client.RestClient;
 
-import java.time.Duration;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.BiFunction;
-
 import static io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport.APPLICATION_JSON;
 import static io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport.TEXT_EVENT_STREAM;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
@@ -298,6 +300,65 @@ void testStructuredOutputValidationSuccess(String clientType) {
 		}
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputWithInHandlerError(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema
+		Map outputSchema = Map.of(
+				"type", "object", "properties", Map.of("result", Map.of("type", "number"), "operation",
+						Map.of("type", "string"), "timestamp", Map.of("type", "string")),
+				"required", List.of("result", "operation"));
+
+		Tool calculatorTool = Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.outputSchema(outputSchema)
+			.build();
+
+		// Handler that returns an error result
+		McpStatelessServerFeatures.SyncToolSpecification tool = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> CallToolResult.builder()
+				.isError(true)
+				.content(List.of(new TextContent("Error calling tool: Simulated in-handler error")))
+				.build())
+			.build();
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			// Verify tool is listed with output schema
+			var toolsList = mcpClient.listTools();
+			assertThat(toolsList.tools()).hasSize(1);
+			assertThat(toolsList.tools().get(0).name()).isEqualTo("calculator");
+			// Note: outputSchema might be null in sync server, but validation still works
+
+			// Call tool with valid structured output
+			CallToolResult response = mcpClient
+				.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3")));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isTrue();
+			assertThat(response.content()).isNotEmpty();
+			assertThat(response.content())
+				.containsExactly(new McpSchema.TextContent("Error calling tool: Simulated in-handler error"));
+			assertThat(response.structuredContent()).isNull();
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testStructuredOutputValidationFailure(String clientType) {
@@ -477,7 +538,7 @@ void testStructuredOutputRuntimeToolAddition(String clientType) {
 	}
 
 	@Test
-	void testThrownMcpError() throws Exception {
+	void testThrownMcpErrorAndJsonRpcError() throws Exception {
 		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
 			.serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -487,7 +548,7 @@ void testThrownMcpError() throws Exception {
 
 		McpStatelessServerFeatures.SyncToolSpecification toolSpec = new McpStatelessServerFeatures.SyncToolSpecification(
 				testTool, (transportContext, request) -> {
-					throw new McpError(new McpSchema.JSONRPCResponse.JSONRPCError(12345, "testing", Map.of("a", "b")));
+					throw new RuntimeException("testing");
 				});
 
 		mcpServer.addTool(toolSpec);
@@ -508,13 +569,16 @@ void testThrownMcpError() throws Exception {
 		request.addHeader("Content-Type", APPLICATION_JSON);
 		request.addHeader("Cache-Control", "no-cache");
 		request.addHeader(HttpHeaders.PROTOCOL_VERSION, ProtocolVersions.MCP_2025_03_26);
+
 		mcpStatelessServerTransport.service(request, response);
 
 		McpSchema.JSONRPCResponse jsonrpcResponse = new ObjectMapper().readValue(response.getContentAsByteArray(),
 				McpSchema.JSONRPCResponse.class);
 
-		assertThat(jsonrpcResponse.error())
-			.isEqualTo(new McpSchema.JSONRPCResponse.JSONRPCError(12345, "testing", Map.of("a", "b")));
+		assertThat(jsonrpcResponse).isNotNull();
+		assertThat(jsonrpcResponse.error()).isNotNull();
+		assertThat(jsonrpcResponse.error().code()).isEqualTo(ErrorCodes.INTERNAL_ERROR);
+		assertThat(jsonrpcResponse.error().message()).isEqualTo("testing");
 
 		mcpServer.close();
 	}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 6899ba474..1f6a1fe58 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -4,28 +4,26 @@
 
 package io.modelcontextprotocol.server;
 
-import static org.assertj.core.api.Assertions.assertThat;
-
-import io.modelcontextprotocol.common.McpTransportContext;
 import java.time.Duration;
 import java.util.Map;
 
-import org.apache.catalina.LifecycleException;
-import org.apache.catalina.LifecycleState;
-import org.apache.catalina.startup.Tomcat;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Timeout;
-
 import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpServer.AsyncSpecification;
 import io.modelcontextprotocol.server.McpServer.SyncSpecification;
 import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
 import io.modelcontextprotocol.server.transport.TomcatTestUtil;
 import jakarta.servlet.http.HttpServletRequest;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Timeout;
+
+import static org.assertj.core.api.Assertions.assertThat;
 
 @Timeout(15)
 class HttpServletStreamableIntegrationTests extends AbstractMcpClientServerIntegrationTests {

From 3f70afd21f8064a8b9549c4624c46316fc1ab2c0 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Mon, 8 Sep 2025 15:30:51 +0200
Subject: [PATCH 068/125] Enhance README with project badges

Added badges for license, build status, Maven Central, and Java version to README.
---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 436104c63..39ba13926 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # MCP Java SDK
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/license/MIT)
 [![Build Status](https://github.com/modelcontextprotocol/java-sdk/actions/workflows/publish-snapshot.yml/badge.svg)](https://github.com/modelcontextprotocol/java-sdk/actions/workflows/publish-snapshot.yml)
+[![Maven Central](https://img.shields.io/maven-central/v/io.modelcontextprotocol.sdk/mcp.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/io.modelcontextprotocol.sdk/mcp)
+[![Java Version](https://img.shields.io/badge/Java-17%2B-orange)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
+
 
 A set of projects that provide Java SDK integration for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture). 
 This SDK enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns.

From bc3a925bdc6eb2ff5d4a4ff3c1220503a6fa0037 Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Fri, 12 Sep 2025 13:59:51 +0200
Subject: [PATCH 069/125] LifecycleInitializer recovers from init failures
 (#549)

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../client/LifecycleInitializer.java               |  1 +
 .../client/LifecycleInitializerTests.java          | 14 +++++++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
index 2cc1c5dba..2fc669c15 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
@@ -289,6 +289,7 @@ public  Mono withIntitialization(String actionName, Function this.initializationRef.get())
 				.timeout(this.initializationTimeout)
 				.onErrorResume(ex -> {
+					this.initializationRef.compareAndSet(newInit, null);
 					return Mono.error(new RuntimeException("Client failed to initialize " + actionName, ex));
 				})
 				.flatMap(operation);
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
index 02021edbf..19de14c24 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
@@ -230,7 +230,10 @@ void shouldHandleConcurrentInitializationRequests() {
 	@Test
 	void shouldHandleInitializationFailure() {
 		when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()))
-			.thenReturn(Mono.error(new RuntimeException("Connection failed")));
+			// fail once
+			.thenReturn(Mono.error(new RuntimeException("Connection failed")))
+			// succeeds on the second call
+			.thenReturn(Mono.just(MOCK_INIT_RESULT));
 
 		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectError(RuntimeException.class)
@@ -238,6 +241,15 @@ void shouldHandleInitializationFailure() {
 
 		assertThat(initializer.isInitialized()).isFalse();
 		assertThat(initializer.currentInitializationResult()).isNull();
+
+		// The initializer can recover from previous errors
+		StepVerifier
+			.create(initializer.withIntitialization("successful init", init -> Mono.just(init.initializeResult())))
+			.expectNext(MOCK_INIT_RESULT)
+			.verifyComplete();
+
+		assertThat(initializer.isInitialized()).isTrue();
+		assertThat(initializer.currentInitializationResult()).isEqualTo(MOCK_INIT_RESULT);
 	}
 
 	@Test

From 7e3ea73815501f19bcc1fa20589ef386a4a760e3 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Sun, 14 Sep 2025 12:07:54 +0200
Subject: [PATCH 070/125] fix: Add JsonInclude annotation to notification
 records for proper serialization (#552)

Add @JsonInclude(JsonInclude.Include.NON_ABSENT) to ResourcesUpdatedNotification
  and to LoggingMessageNotification

This ensures that absent (null/Optional.empty()) fields are excluded from JSON
serialization, preventing potential serialization issues with these MCP notification types.

Signed-off-by: Christian Tzolov 
---
 mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 3f8150271..4e8b0fa06 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -2203,6 +2203,7 @@ public ProgressNotification(String progressToken, double progress, Double total,
 	 * @param uri The updated resource uri.
 	 * @param meta See specification for notes on _meta usage
 	 */
+	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ResourcesUpdatedNotification(// @formatter:off
 		@JsonProperty("uri") String uri,
@@ -2224,6 +2225,7 @@ public ResourcesUpdatedNotification(String uri) {
 	 * @param data JSON-serializable logging data.
 	 * @param meta See specification for notes on _meta usage
 	 */
+	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record LoggingMessageNotification( // @formatter:off
 		@JsonProperty("level") LoggingLevel level,

From d8959ef854aa75748bfa6d383c256bc9db2a8836 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Mon, 15 Sep 2025 14:22:06 +0200
Subject: [PATCH 071/125] fix: support valid JSON value in tool structured
 content output (#551)

- Change CallToolResult.structuredContent type from Map to Object
  to support both objects and arrays
- Update JsonSchemaValidator to validate any Object type, not just Maps
- Add test cases for array-type structured output validation
- Fix type casting in existing tests to handle the more generic Object type
- Deprecate CallToolResult constructors in favor of builder pattern
- Update server implementations to use CallToolResult builder

This allows tools to return arrays as structured content, not just objects,
which is required by the MCP specification for tools with array-type output schemas.

It is realated to MPC spec fix: https://github.com/modelcontextprotocol/modelcontextprotocol/issues/834

Fixes #550

BREAKING CHANGE!

Migration Guide:
----------------
1. If you're accessing CallToolResult.structuredContent():
   - Add explicit casting when you know it's a Map:
     Before: result.structuredContent().get("key")
     After:  ((Map) result.structuredContent()).get("key")

   - Or check the type first:
     if (result.structuredContent() instanceof Map) {
         Map map = (Map) result.structuredContent();
         // use map
     } else if (result.structuredContent() instanceof List) {
         List list = (List) result.structuredContent();
         // use list
     }

2. If you're creating CallToolResult instances:
   - Switch to using the builder pattern:
     Before: new CallToolResult(content, isError, structuredContent)
     After:  CallToolResult.builder()
               .content(content)
               .isError(isError)
               .structuredContent(structuredContent)
               .build()

3. If you're implementing JsonSchemaValidator:
   - Update your validate() method signature:
     Before: validate(Map schema, Map structuredContent)
     After:  validate(Map schema, Object structuredContent)

Signed-off-by: Christian Tzolov 
---
 ...stractMcpClientServerIntegrationTests.java | 76 ++++++++++++++++---
 .../AbstractStatelessIntegrationTests.java    | 63 ++++++++++++++-
 .../server/McpAsyncServer.java                | 20 ++---
 .../server/McpStatelessAsyncServer.java       |  7 +-
 .../spec/DefaultJsonSchemaValidator.java      |  2 +-
 .../spec/JsonSchemaValidator.java             |  2 +-
 .../modelcontextprotocol/spec/McpSchema.java  | 26 ++++---
 ...stractMcpClientServerIntegrationTests.java | 61 ++++++++++++++-
 .../HttpServletStatelessIntegrationTests.java | 61 +++++++++++++++
 .../spec/McpSchemaTests.java                  |  4 +-
 10 files changed, 283 insertions(+), 39 deletions(-)

diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index dd3bc59da..113c8d1c2 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -1411,7 +1411,7 @@ void testStructuredOutputValidationSuccess(String clientType) {
 
 			// In WebMVC, structured content is returned properly
 			if (response.structuredContent() != null) {
-				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+				assertThat((Map) response.structuredContent()).containsEntry("result", 5.0)
 					.containsEntry("operation", "2 + 3")
 					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
 			}
@@ -1433,7 +1433,66 @@ void testStructuredOutputValidationSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputOfObjectArrayValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema that returns an array of objects
+		Map outputSchema = Map
+			.of( // @formatter:off
+			"type", "array",
+			"items", Map.of(
+				"type", "object",
+				"properties", Map.of(
+					"name", Map.of("type", "string"),
+					"age", Map.of("type", "number")),					
+				"required", List.of("name", "age"))); // @formatter:on
+
+		Tool calculatorTool = Tool.builder()
+			.name("getMembers")
+			.description("Returns a list of members")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				return CallToolResult.builder()
+					.structuredContent(List.of(Map.of("name", "John", "age", 30), Map.of("name", "Peter", "age", 25)))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			// Call tool with valid structured output of type array
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("getMembers", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isArray()
+				.hasSize(2)
+				.containsExactlyInAnyOrder(json("""
+						{"name":"John","age":30}"""), json("""
+						{"name":"Peter","age":25}"""));
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
 	void testStructuredOutputWithInHandlerError(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -1449,16 +1508,13 @@ void testStructuredOutputWithInHandlerError(String clientType) {
 			.outputSchema(outputSchema)
 			.build();
 
-		// Handler that throws an exception to simulate an error
+		// Handler that returns an error result
 		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(calculatorTool)
-			.callHandler((exchange, request) -> {
-
-				return CallToolResult.builder()
-					.isError(true)
-					.content(List.of(new TextContent("Error calling tool: Simulated in-handler error")))
-					.build();
-			})
+			.callHandler((exchange, request) -> CallToolResult.builder()
+				.isError(true)
+				.content(List.of(new TextContent("Error calling tool: Simulated in-handler error")))
+				.build())
 			.build();
 
 		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
index c96f10eda..d4a84c7c8 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
@@ -274,7 +274,6 @@ void testInitialize(String clientType) {
 	// ---------------------------------------
 	// Tool Structured Output Schema Tests
 	// ---------------------------------------
-
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testStructuredOutputValidationSuccess(String clientType) {
@@ -329,7 +328,7 @@ void testStructuredOutputValidationSuccess(String clientType) {
 
 			// In WebMVC, structured content is returned properly
 			if (response.structuredContent() != null) {
-				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+				assertThat((Map) response.structuredContent()).containsEntry("result", 5.0)
 					.containsEntry("operation", "2 + 3")
 					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
 			}
@@ -350,6 +349,66 @@ void testStructuredOutputValidationSuccess(String clientType) {
 		}
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testStructuredOutputOfObjectArrayValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema that returns an array of objects
+		Map outputSchema = Map
+			.of( // @formatter:off
+			"type", "array",
+			"items", Map.of(
+				"type", "object",
+				"properties", Map.of(
+					"name", Map.of("type", "string"),
+					"age", Map.of("type", "number")),					
+				"required", List.of("name", "age"))); // @formatter:on
+
+		Tool calculatorTool = Tool.builder()
+			.name("getMembers")
+			.description("Returns a list of members")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				return CallToolResult.builder()
+					.structuredContent(List.of(Map.of("name", "John", "age", 30), Map.of("name", "Peter", "age", 25)))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			// Call tool with valid structured output of type array
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("getMembers", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isArray()
+				.hasSize(2)
+				.containsExactlyInAnyOrder(json("""
+						{"name":"John","age":30}"""), json("""
+						{"name":"Peter","age":25}"""));
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testStructuredOutputWithInHandlerError(String clientType) {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index 3c8057a72..ba97174a0 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -15,15 +15,9 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.BiFunction;
 
-import io.modelcontextprotocol.spec.DefaultMcpStreamableServerSessionFactory;
-import io.modelcontextprotocol.spec.McpServerTransportProviderBase;
-import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
-
+import io.modelcontextprotocol.spec.DefaultMcpStreamableServerSessionFactory;
 import io.modelcontextprotocol.spec.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpError;
@@ -34,14 +28,17 @@
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
 import io.modelcontextprotocol.spec.McpSchema.SetLevelRequest;
-import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import io.modelcontextprotocol.spec.McpServerTransportProviderBase;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.Utils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
@@ -420,8 +417,11 @@ public Mono apply(McpAsyncServerExchange exchange, McpSchema.Cal
 					// TextContent block.)
 					// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
 
-					return new CallToolResult(List.of(new McpSchema.TextContent(validation.jsonStructuredOutput())),
-							result.isError(), result.structuredContent());
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent(validation.jsonStructuredOutput())))
+						.isError(result.isError())
+						.structuredContent(result.structuredContent())
+						.build();
 				}
 
 				return result;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 50d45b14c..ee5a4d354 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -293,8 +293,11 @@ public Mono apply(McpTransportContext transportContext, McpSchem
 					// TextContent block.)
 					// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
 
-					return new CallToolResult(List.of(new McpSchema.TextContent(validation.jsonStructuredOutput())),
-							result.isError(), result.structuredContent());
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent(validation.jsonStructuredOutput())))
+						.isError(result.isError())
+						.structuredContent(result.structuredContent())
+						.build();
 				}
 
 				return result;
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
index f4bdc02eb..345194465 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
@@ -51,7 +51,7 @@ public DefaultJsonSchemaValidator(ObjectMapper objectMapper) {
 	}
 
 	@Override
-	public ValidationResponse validate(Map schema, Map structuredContent) {
+	public ValidationResponse validate(Map schema, Object structuredContent) {
 
 		Assert.notNull(schema, "Schema must not be null");
 		Assert.notNull(structuredContent, "Structured content must not be null");
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java b/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
index 572d7c043..4a42c9ff3 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
@@ -40,6 +40,6 @@ public static ValidationResponse asInvalid(String message) {
 	 * @return A ValidationResponse indicating whether the validation was successful or
 	 * not.
 	 */
-	ValidationResponse validate(Map schema, Map structuredContent);
+	ValidationResponse validate(Map schema, Object structuredContent);
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 4e8b0fa06..ea823b04b 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -11,9 +11,6 @@
 import java.util.List;
 import java.util.Map;
 
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
@@ -23,8 +20,9 @@
 import com.fasterxml.jackson.annotation.JsonTypeInfo.As;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.util.Assert;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * Based on the JSON-RPC 2.0
@@ -1508,15 +1506,21 @@ public CallToolRequest build() {
 	public record CallToolResult( // @formatter:off
 		@JsonProperty("content") List content,
 		@JsonProperty("isError") Boolean isError,
-		@JsonProperty("structuredContent") Map structuredContent,
+		@JsonProperty("structuredContent") Object structuredContent,
 		@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
 
-		// backwards compatibility constructor
+		/**
+		 * @deprecated use the builder instead.
+		 */
+		@Deprecated
 		public CallToolResult(List content, Boolean isError) {
-			this(content, isError, null, null);
+			this(content, isError, (Object) null, null);
 		}
 
-		// backwards compatibility constructor
+		/**
+		 * @deprecated use the builder instead.
+		 */
+		@Deprecated
 		public CallToolResult(List content, Boolean isError, Map structuredContent) {
 			this(content, isError, structuredContent, null);
 		}
@@ -1551,7 +1555,7 @@ public static class Builder {
 
 			private Boolean isError = false;
 
-			private Map structuredContent;
+			private Object structuredContent;
 
 			private Map meta;
 
@@ -1566,7 +1570,7 @@ public Builder content(List content) {
 				return this;
 			}
 
-			public Builder structuredContent(Map structuredContent) {
+			public Builder structuredContent(Object structuredContent) {
 				Assert.notNull(structuredContent, "structuredContent must not be null");
 				this.structuredContent = structuredContent;
 				return this;
@@ -1644,7 +1648,7 @@ public Builder meta(Map meta) {
 			 * @return a new CallToolResult instance
 			 */
 			public CallToolResult build() {
-				return new CallToolResult(content, isError, structuredContent, meta);
+				return new CallToolResult(content, isError, (Object) structuredContent, meta);
 			}
 
 		}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index 8dae452f0..7503a2700 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -1407,7 +1407,7 @@ void testStructuredOutputValidationSuccess(String clientType) {
 
 			// In WebMVC, structured content is returned properly
 			if (response.structuredContent() != null) {
-				assertThat(response.structuredContent()).containsEntry("result", 5.0)
+				assertThat((Map) response.structuredContent()).containsEntry("result", 5.0)
 					.containsEntry("operation", "2 + 3")
 					.containsEntry("timestamp", "2024-01-01T10:00:00Z");
 			}
@@ -1428,6 +1428,65 @@ void testStructuredOutputValidationSuccess(String clientType) {
 		}
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputOfObjectArrayValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema that returns an array of objects
+		Map outputSchema = Map
+			.of( // @formatter:off
+			"type", "array",
+			"items", Map.of(
+				"type", "object",
+				"properties", Map.of(
+					"name", Map.of("type", "string"),
+					"age", Map.of("type", "number")),					
+				"required", List.of("name", "age"))); // @formatter:on
+
+		Tool calculatorTool = Tool.builder()
+			.name("getMembers")
+			.description("Returns a list of members")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				return CallToolResult.builder()
+					.structuredContent(List.of(Map.of("name", "John", "age", 30), Map.of("name", "Peter", "age", 25)))
+					.build();
+			})
+			.build();
+
+		var mcpServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			// Call tool with valid structured output of type array
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("getMembers", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isArray()
+				.hasSize(2)
+				.containsExactlyInAnyOrder(json("""
+						{"name":"John","age":30}"""), json("""
+						{"name":"Peter","age":25}"""));
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testStructuredOutputWithInHandlerError(String clientType) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index 5cc7d61be..732b2ba06 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -300,6 +300,67 @@ void testStructuredOutputValidationSuccess(String clientType) {
 		}
 	}
 
+	@ParameterizedTest(name = "{0} : {displayName} ")
+	@ValueSource(strings = { "httpclient" })
+	void testStructuredOutputOfObjectArrayValidationSuccess(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		// Create a tool with output schema that returns an array of objects
+		Map outputSchema = Map
+			.of( // @formatter:off
+			"type", "array",
+			"items", Map.of(
+				"type", "object",
+				"properties", Map.of(
+					"name", Map.of("type", "string"),
+					"age", Map.of("type", "number")),					
+				"required", List.of("name", "age"))); // @formatter:on
+
+		Tool calculatorTool = Tool.builder()
+			.name("getMembers")
+			.description("Returns a list of members")
+			.outputSchema(outputSchema)
+			.build();
+
+		McpStatelessServerFeatures.SyncToolSpecification tool = McpStatelessServerFeatures.SyncToolSpecification
+			.builder()
+			.tool(calculatorTool)
+			.callHandler((exchange, request) -> {
+				return CallToolResult.builder()
+					.structuredContent(List.of(Map.of("name", "John", "age", 30), Map.of("name", "Peter", "age", 25)))
+					.build();
+			})
+			.build();
+
+		var mcpServer = McpServer.sync(mcpStatelessServerTransport)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().tools(true).build())
+			.tools(tool)
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+			assertThat(mcpClient.initialize()).isNotNull();
+
+			// Call tool with valid structured output of type array
+			CallToolResult response = mcpClient.callTool(new McpSchema.CallToolRequest("getMembers", Map.of()));
+
+			assertThat(response).isNotNull();
+			assertThat(response.isError()).isFalse();
+
+			assertThat(response.structuredContent()).isNotNull();
+			assertThatJson(response.structuredContent()).when(Option.IGNORING_ARRAY_ORDER)
+				.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
+				.isArray()
+				.hasSize(2)
+				.containsExactlyInAnyOrder(json("""
+						{"name":"John","age":30}"""), json("""
+						{"name":"Peter","age":25}"""));
+		}
+		finally {
+			mcpServer.closeGracefully();
+		}
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testStructuredOutputWithInHandlerError(String clientType) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index a5b2137fd..81552100f 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -1206,7 +1206,9 @@ void testCallToolRequestBuilderNameRequired() {
 	void testCallToolResult() throws Exception {
 		McpSchema.TextContent content = new McpSchema.TextContent("Tool execution result");
 
-		McpSchema.CallToolResult result = new McpSchema.CallToolResult(Collections.singletonList(content), false);
+		McpSchema.CallToolResult result = McpSchema.CallToolResult.builder()
+			.content(Collections.singletonList(content))
+			.build();
 
 		String value = mapper.writeValueAsString(result);
 

From 80d0ad82a6b88a8ce8756dad3d4c90c4ae62ca69 Mon Sep 17 00:00:00 2001
From: Graeme Rocher 
Date: Wed, 10 Sep 2025 12:26:17 +0200
Subject: [PATCH 072/125] feat: Introduce McpJsonMapper interface to decouple
 from Jackson (#543)

This pull request creates two modules, `mcp-json` and `mcp-json-jackson`. It removes the `com.fasterxml.jackson.core:jackson-databind` and `com.networknt:json-schema-validator` dependencies from the `mcp` module. The `mcp` module now only depends on `com.fasterxml.jackson.core:jackson-annotations`.

To use Jackson, you have to add `mcp-jackson` to your dependencies in addition to `mcp`. I added the dependency `mcp-jackson` to both `mcp-spring-mvc` and `mcp-spring-webflux` to avoid a breaking change in those modules.

It provides two [SPI](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html) `JsonSchemaValidatorSupplier` and `JacksonJsonSchemaValidatorSupplier` to allow easy replacement for consumers who don't want to use Jackson.

This pull request also ensures no `McpJsonMapper` is instantiated if one is provided via a builder method. Only if the builders don't receive a `McpJsonMapper` mapper, one is instantiated in the `build` method of the builder.
The logic behind this is to allow frameworks to provide a `McpJsonMapper` mapper singleton implementation and feed it to the builders without paying the price of instantiating `McpJsonMappers`, which will not be used. The goal is to be able to use the `ObjectMapper` singleton of an application also for the MCP code.

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                               |  14 ++
 mcp-json-jackson2/pom.xml                     |  53 ++++
 .../json/jackson/JacksonMcpJsonMapper.java    |  87 +++++++
 .../jackson/JacksonMcpJsonMapperSupplier.java |  32 +++
 .../jackson}/DefaultJsonSchemaValidator.java  |  14 +-
 .../JacksonJsonSchemaValidatorSupplier.java   |  29 +++
 ...contextprotocol.json.McpJsonMapperSupplier |   1 +
 ...ol.json.schema.JsonSchemaValidatorSupplier |   1 +
 mcp-json/pom.xml                              |  39 +++
 .../json/McpJsonInternal.java                 |  84 +++++++
 .../json/McpJsonMapper.java                   | 110 +++++++++
 .../json/McpJsonMapperSupplier.java           |  14 ++
 .../io/modelcontextprotocol/json/TypeRef.java |  44 ++++
 .../json/schema/JsonSchemaInternal.java       |  83 +++++++
 .../json/schema/JsonSchemaValidator.java      |  64 +++++
 .../schema/JsonSchemaValidatorSupplier.java   |  19 ++
 mcp-spring/mcp-spring-webflux/pom.xml         |   8 +-
 .../WebClientStreamableHttpTransport.java     |  39 ++-
 .../transport/WebFluxSseClientTransport.java  |  59 ++---
 .../WebFluxSseServerTransportProvider.java    | 116 ++-------
 .../WebFluxStatelessServerTransport.java      |  46 ++--
 ...FluxStreamableServerTransportProvider.java |  52 ++--
 .../WebFluxSseIntegrationTests.java           |   3 -
 .../WebFluxStatelessIntegrationTests.java     |   4 -
 .../WebFluxStreamableIntegrationTests.java    |   3 -
 .../client/WebFluxSseMcpSyncClientTests.java  |   1 -
 .../WebFluxSseClientTransportTests.java       |  20 +-
 ...erMcpTransportContextIntegrationTests.java |   4 -
 ...erMcpTransportContextIntegrationTests.java |   4 -
 .../server/WebFluxSseMcpAsyncServerTests.java |   4 +-
 .../server/WebFluxSseMcpSyncServerTests.java  |   5 +-
 .../WebFluxStreamableMcpAsyncServerTests.java |   2 -
 .../WebFluxStreamableMcpSyncServerTests.java  |   2 -
 .../utils/McpJsonMapperUtils.java             |  12 +
 mcp-spring/mcp-spring-webmvc/pom.xml          |   8 +-
 .../WebMvcSseServerTransportProvider.java     | 116 ++-------
 .../WebMvcStatelessServerTransport.java       |  29 ++-
 ...bMvcStreamableServerTransportProvider.java |  49 ++--
 .../McpTransportContextIntegrationTests.java  |  13 +-
 ...cpStreamableAsyncServerTransportTests.java |   7 +-
 ...McpStreamableSyncServerTransportTests.java |   7 +-
 .../WebMvcSseAsyncServerTransportTests.java   |   6 +-
 .../WebMvcSseCustomContextPathTests.java      |   2 -
 .../server/WebMvcSseIntegrationTests.java     |   3 -
 .../WebMvcSseSyncServerTransportTests.java    |   6 +-
 .../WebMvcStatelessIntegrationTests.java      |   7 +-
 .../WebMvcStreamableIntegrationTests.java     |   3 -
 ...stractMcpClientServerIntegrationTests.java |  44 ++--
 .../AbstractStatelessIntegrationTests.java    |  18 +-
 .../MockMcpTransport.java                     |   8 +-
 .../client/AbstractMcpAsyncClientTests.java   |  11 +-
 .../client/AbstractMcpSyncClientTests.java    |   2 -
 .../server/AbstractMcpAsyncServerTests.java   |  57 +++--
 .../server/AbstractMcpSyncServerTests.java    |  47 ++--
 .../utils/McpJsonMapperUtils.java             |  12 +
 .../utils/ToolsUtils.java                     |  15 ++
 mcp/pom.xml                                   |  22 +-
 .../client/McpAsyncClient.java                |  37 ++-
 .../HttpClientSseClientTransport.java         | 115 ++-------
 .../HttpClientStreamableHttpTransport.java    |  42 ++--
 .../transport/StdioClientTransport.java       |  33 +--
 .../server/McpAsyncServer.java                |  43 ++--
 .../server/McpAsyncServerExchange.java        |  10 +-
 .../server/McpServer.java                     | 140 +++++------
 .../server/McpServerFeatures.java             |  11 +-
 .../server/McpStatelessAsyncServer.java       |  27 +--
 ...HttpServletSseServerTransportProvider.java | 118 +++------
 .../HttpServletStatelessServerTransport.java  |  35 ++-
 ...vletStreamableServerTransportProvider.java |  55 +++--
 .../StdioServerTransportProvider.java         |  36 ++-
 .../spec/McpClientSession.java                |   4 +-
 .../modelcontextprotocol/spec/McpSchema.java  | 100 ++------
 .../spec/McpServerSession.java                |   6 +-
 .../modelcontextprotocol/spec/McpSession.java |   4 +-
 .../spec/McpStreamableServerSession.java      |   6 +-
 .../spec/McpTransport.java                    |   4 +-
 .../spec/MissingMcpTransportSession.java      |   4 +-
 .../util/KeepAliveScheduler.java              |   4 +-
 .../MockMcpClientTransport.java               |   8 +-
 .../MockMcpServerTransport.java               |   8 +-
 .../client/AbstractMcpAsyncClientTests.java   |  10 +-
 .../client/AbstractMcpSyncClientTests.java    |   2 -
 ...pClientStreamableHttpAsyncClientTests.java |   1 -
 .../McpAsyncClientResponseHandlerTests.java   |  31 ++-
 .../client/McpAsyncClientTests.java           |  15 +-
 .../client/ServerParameterUtils.java          |  19 ++
 .../client/StdioMcpAsyncClientTests.java      |  16 +-
 .../client/StdioMcpSyncClientTests.java       |  16 +-
 .../HttpClientSseClientTransportTests.java    |   7 +-
 ...HttpClientStreamableHttpTransportTest.java |   1 -
 ...erMcpTransportContextIntegrationTests.java |   4 -
 ...erMcpTransportContextIntegrationTests.java |   4 -
 .../server/AbstractMcpAsyncServerTests.java   |  66 +++--
 ...stractMcpClientServerIntegrationTests.java |  45 ++--
 .../server/AbstractMcpSyncServerTests.java    |  60 +++--
 .../AsyncToolSpecificationBuilderTest.java    |  50 +++-
 .../HttpServletSseIntegrationTests.java       |   2 -
 .../HttpServletStatelessIntegrationTests.java |  20 +-
 ...HttpServletStreamableAsyncServerTests.java |   7 +-
 ...HttpServletStreamableIntegrationTests.java |   2 -
 .../HttpServletStreamableSyncServerTests.java |   7 +-
 .../server/McpAsyncServerExchangeTests.java   |  60 +++--
 .../server/McpCompletionTests.java            |   4 +-
 .../server/McpSyncServerExchangeTests.java    |  60 +++--
 .../server/StdioMcpAsyncServerTests.java      |   4 +-
 .../server/StdioMcpSyncServerTests.java       |   4 +-
 .../SyncToolSpecificationBuilderTest.java     |  19 +-
 ...ervletSseServerCustomContextPathTests.java |   3 -
 .../StdioServerTransportProviderTests.java    |  14 +-
 .../spec/DefaultJsonSchemaValidatorTests.java |   3 +-
 .../spec/McpClientSessionTests.java           |   4 +-
 .../spec/McpSchemaTests.java                  | 228 ++++++++++--------
 .../spec/json/gson/GsonMcpJsonMapper.java     |  97 ++++++++
 .../json/gson/GsonMcpJsonMapperTests.java     | 132 ++++++++++
 .../util/KeepAliveSchedulerTests.java         |   4 +-
 .../util/McpJsonMapperUtils.java              |  12 +
 .../modelcontextprotocol/util/ToolsUtils.java |  15 ++
 pom.xml                                       |   2 +
 118 files changed, 2043 insertions(+), 1421 deletions(-)
 create mode 100644 mcp-json-jackson2/pom.xml
 create mode 100644 mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapper.java
 create mode 100644 mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapperSupplier.java
 rename {mcp/src/main/java/io/modelcontextprotocol/spec => mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson}/DefaultJsonSchemaValidator.java (94%)
 create mode 100644 mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/JacksonJsonSchemaValidatorSupplier.java
 create mode 100644 mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.McpJsonMapperSupplier
 create mode 100644 mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.schema.JsonSchemaValidatorSupplier
 create mode 100644 mcp-json/pom.xml
 create mode 100644 mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonInternal.java
 create mode 100644 mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java
 create mode 100644 mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapperSupplier.java
 create mode 100644 mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java
 create mode 100644 mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaInternal.java
 create mode 100644 mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidator.java
 create mode 100644 mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidatorSupplier.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
 create mode 100644 mcp-test/src/main/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
 create mode 100644 mcp-test/src/main/java/io/modelcontextprotocol/utils/ToolsUtils.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
 create mode 100644 mcp/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index ac68e55bc..b7ea52639 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -33,6 +33,20 @@
                 ${project.version}
             
 
+            
+            
+                io.modelcontextprotocol.sdk
+                mcp-json
+                ${project.version}
+            
+
+            
+            
+                io.modelcontextprotocol.sdk
+                mcp-json-jackson2
+                ${project.version}
+            
+
             
             
                 io.modelcontextprotocol.sdk
diff --git a/mcp-json-jackson2/pom.xml b/mcp-json-jackson2/pom.xml
new file mode 100644
index 000000000..25159a9fe
--- /dev/null
+++ b/mcp-json-jackson2/pom.xml
@@ -0,0 +1,53 @@
+
+
+	4.0.0
+	
+		io.modelcontextprotocol.sdk
+		mcp-parent
+		0.13.0-SNAPSHOT
+	
+	mcp-json-jackson2
+	jar
+	Java MCP SDK JSON Jackson
+	Java MCP SDK JSON implementation based on Jackson
+	https://github.com/modelcontextprotocol/java-sdk
+	
+		https://github.com/modelcontextprotocol/java-sdk
+		git://github.com/modelcontextprotocol/java-sdk.git
+		git@github.com/modelcontextprotocol/java-sdk.git
+	
+	
+		
+			
+				org.apache.maven.plugins
+				maven-jar-plugin
+				
+					
+                        
+                            true
+                        
+					
+				
+			
+		
+	
+	
+        
+            io.modelcontextprotocol.sdk
+            mcp-json
+            0.13.0-SNAPSHOT
+        
+        
+            com.fasterxml.jackson.core
+            jackson-databind
+            ${jackson.version}
+        
+        
+            com.networknt
+            json-schema-validator
+            ${json-schema-validator.version}
+        
+	
+
diff --git a/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapper.java b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapper.java
new file mode 100644
index 000000000..6aa2b4ebc
--- /dev/null
+++ b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapper.java
@@ -0,0 +1,87 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json.jackson;
+
+import com.fasterxml.jackson.databind.JavaType;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
+
+import java.io.IOException;
+
+/**
+ * Jackson-based implementation of JsonMapper. Wraps a Jackson ObjectMapper but keeps the
+ * SDK decoupled from Jackson at the API level.
+ */
+public final class JacksonMcpJsonMapper implements McpJsonMapper {
+
+	private final ObjectMapper objectMapper;
+
+	/**
+	 * Constructs a new JacksonMcpJsonMapper instance with the given ObjectMapper.
+	 * @param objectMapper the ObjectMapper to be used for JSON serialization and
+	 * deserialization. Must not be null.
+	 * @throws IllegalArgumentException if the provided ObjectMapper is null.
+	 */
+	public JacksonMcpJsonMapper(ObjectMapper objectMapper) {
+		if (objectMapper == null) {
+			throw new IllegalArgumentException("ObjectMapper must not be null");
+		}
+		this.objectMapper = objectMapper;
+	}
+
+	/**
+	 * Returns the underlying Jackson {@link ObjectMapper} used for JSON serialization and
+	 * deserialization.
+	 * @return the ObjectMapper instance
+	 */
+	public ObjectMapper getObjectMapper() {
+		return objectMapper;
+	}
+
+	@Override
+	public  T readValue(String content, Class type) throws IOException {
+		return objectMapper.readValue(content, type);
+	}
+
+	@Override
+	public  T readValue(byte[] content, Class type) throws IOException {
+		return objectMapper.readValue(content, type);
+	}
+
+	@Override
+	public  T readValue(String content, TypeRef type) throws IOException {
+		JavaType javaType = objectMapper.getTypeFactory().constructType(type.getType());
+		return objectMapper.readValue(content, javaType);
+	}
+
+	@Override
+	public  T readValue(byte[] content, TypeRef type) throws IOException {
+		JavaType javaType = objectMapper.getTypeFactory().constructType(type.getType());
+		return objectMapper.readValue(content, javaType);
+	}
+
+	@Override
+	public  T convertValue(Object fromValue, Class type) {
+		return objectMapper.convertValue(fromValue, type);
+	}
+
+	@Override
+	public  T convertValue(Object fromValue, TypeRef type) {
+		JavaType javaType = objectMapper.getTypeFactory().constructType(type.getType());
+		return objectMapper.convertValue(fromValue, javaType);
+	}
+
+	@Override
+	public String writeValueAsString(Object value) throws IOException {
+		return objectMapper.writeValueAsString(value);
+	}
+
+	@Override
+	public byte[] writeValueAsBytes(Object value) throws IOException {
+		return objectMapper.writeValueAsBytes(value);
+	}
+
+}
diff --git a/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapperSupplier.java b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapperSupplier.java
new file mode 100644
index 000000000..0e79c3e0e
--- /dev/null
+++ b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/jackson/JacksonMcpJsonMapperSupplier.java
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json.jackson;
+
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.McpJsonMapperSupplier;
+
+/**
+ * A supplier of {@link McpJsonMapper} instances that uses the Jackson library for JSON
+ * serialization and deserialization.
+ * 

+ * This implementation provides a {@link McpJsonMapper} backed by a Jackson
+ * {@link com.fasterxml.jackson.databind.ObjectMapper}.
+ */
+public class JacksonMcpJsonMapperSupplier implements McpJsonMapperSupplier {
+
+	/**
+	 * Returns a new instance of {@link McpJsonMapper} that uses the Jackson library for
+	 * JSON serialization and deserialization.
+	 * 

+	 * The returned {@link McpJsonMapper} is backed by a new instance of
+	 * {@link com.fasterxml.jackson.databind.ObjectMapper}.
+	 * @return a new {@link McpJsonMapper} instance
+	 */
+	@Override
+	public McpJsonMapper get() {
+		return new JacksonMcpJsonMapper(new com.fasterxml.jackson.databind.ObjectMapper());
+	}
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
similarity index 94%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
rename to mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
index 345194465..7ec0419c8 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidator.java
+++ b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
@@ -1,13 +1,13 @@
 /*
  * Copyright 2024-2024 the original author or authors.
  */
-
-package io.modelcontextprotocol.spec;
+package io.modelcontextprotocol.json.schema.jackson;
 
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -20,8 +20,6 @@
 import com.networknt.schema.SpecVersion;
 import com.networknt.schema.ValidationMessage;
 
-import io.modelcontextprotocol.util.Assert;
-
 /**
  * Default implementation of the {@link JsonSchemaValidator} interface. This class
  * provides methods to validate structured content against a JSON schema. It uses the
@@ -53,8 +51,12 @@ public DefaultJsonSchemaValidator(ObjectMapper objectMapper) {
 	@Override
 	public ValidationResponse validate(Map schema, Object structuredContent) {
 
-		Assert.notNull(schema, "Schema must not be null");
-		Assert.notNull(structuredContent, "Structured content must not be null");
+		if (schema == null) {
+			throw new IllegalArgumentException("Schema must not be null");
+		}
+		if (structuredContent == null) {
+			throw new IllegalArgumentException("Structured content must not be null");
+		}
 
 		try {
 
diff --git a/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/JacksonJsonSchemaValidatorSupplier.java b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/JacksonJsonSchemaValidatorSupplier.java
new file mode 100644
index 000000000..86153a538
--- /dev/null
+++ b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/JacksonJsonSchemaValidatorSupplier.java
@@ -0,0 +1,29 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json.schema.jackson;
+
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidatorSupplier;
+
+/**
+ * A concrete implementation of {@link JsonSchemaValidatorSupplier} that provides a
+ * {@link JsonSchemaValidator} instance based on the Jackson library.
+ *
+ * @see JsonSchemaValidatorSupplier
+ * @see JsonSchemaValidator
+ */
+public class JacksonJsonSchemaValidatorSupplier implements JsonSchemaValidatorSupplier {
+
+	/**
+	 * Returns a new instance of {@link JsonSchemaValidator} that uses the Jackson library
+	 * for JSON schema validation.
+	 * @return A {@link JsonSchemaValidator} instance.
+	 */
+	@Override
+	public JsonSchemaValidator get() {
+		return new DefaultJsonSchemaValidator();
+	}
+
+}
diff --git a/mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.McpJsonMapperSupplier b/mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.McpJsonMapperSupplier
new file mode 100644
index 000000000..8ea66d698
--- /dev/null
+++ b/mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.McpJsonMapperSupplier
@@ -0,0 +1 @@
+io.modelcontextprotocol.json.jackson.JacksonMcpJsonMapperSupplier
\ No newline at end of file
diff --git a/mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.schema.JsonSchemaValidatorSupplier b/mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.schema.JsonSchemaValidatorSupplier
new file mode 100644
index 000000000..0fb0b7e5a
--- /dev/null
+++ b/mcp-json-jackson2/src/main/resources/META-INF/services/io.modelcontextprotocol.json.schema.JsonSchemaValidatorSupplier
@@ -0,0 +1 @@
+io.modelcontextprotocol.json.schema.jackson.JacksonJsonSchemaValidatorSupplier
\ No newline at end of file
diff --git a/mcp-json/pom.xml b/mcp-json/pom.xml
new file mode 100644
index 000000000..037ef2ac4
--- /dev/null
+++ b/mcp-json/pom.xml
@@ -0,0 +1,39 @@
+
+
+	4.0.0
+	
+		io.modelcontextprotocol.sdk
+		mcp-parent
+		0.13.0-SNAPSHOT
+	
+	mcp-json
+	jar
+	Java MCP SDK JSON Support
+	Java MCP SDK JSON Support API
+	https://github.com/modelcontextprotocol/java-sdk
+	
+		https://github.com/modelcontextprotocol/java-sdk
+		git://github.com/modelcontextprotocol/java-sdk.git
+		git@github.com/modelcontextprotocol/java-sdk.git
+	
+	
+		
+			
+				org.apache.maven.plugins
+				maven-jar-plugin
+				
+					
+                        
+                            true
+                        
+					
+				
+			
+		
+	
+	
+
+    
+
diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonInternal.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonInternal.java
new file mode 100644
index 000000000..31930ab33
--- /dev/null
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonInternal.java
@@ -0,0 +1,84 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json;
+
+import java.util.ServiceLoader;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.stream.Stream;
+
+/**
+ * Utility class for creating a default {@link McpJsonMapper} instance. This class
+ * provides a single method to create a default mapper using the {@link ServiceLoader}
+ * mechanism.
+ */
+final class McpJsonInternal {
+
+	private static McpJsonMapper defaultJsonMapper = null;
+
+	/**
+	 * Returns the cached default {@link McpJsonMapper} instance. If the default mapper
+	 * has not been created yet, it will be initialized using the
+	 * {@link #createDefaultMapper()} method.
+	 * @return the default {@link McpJsonMapper} instance
+	 * @throws IllegalStateException if no default {@link McpJsonMapper} implementation is
+	 * found
+	 */
+	static McpJsonMapper getDefaultMapper() {
+		if (defaultJsonMapper == null) {
+			defaultJsonMapper = McpJsonInternal.createDefaultMapper();
+		}
+		return defaultJsonMapper;
+	}
+
+	/**
+	 * Creates a default {@link McpJsonMapper} instance using the {@link ServiceLoader}
+	 * mechanism. The default mapper is resolved by loading the first available
+	 * {@link McpJsonMapperSupplier} implementation on the classpath.
+	 * @return the default {@link McpJsonMapper} instance
+	 * @throws IllegalStateException if no default {@link McpJsonMapper} implementation is
+	 * found
+	 */
+	static McpJsonMapper createDefaultMapper() {
+		AtomicReference ex = new AtomicReference<>();
+		return ServiceLoader.load(McpJsonMapperSupplier.class).stream().flatMap(p -> {
+			try {
+				McpJsonMapperSupplier supplier = p.get();
+				return Stream.ofNullable(supplier);
+			}
+			catch (Exception e) {
+				addException(ex, e);
+				return Stream.empty();
+			}
+		}).flatMap(jsonMapperSupplier -> {
+			try {
+				return Stream.ofNullable(jsonMapperSupplier.get());
+			}
+			catch (Exception e) {
+				addException(ex, e);
+				return Stream.empty();
+			}
+		}).findFirst().orElseThrow(() -> {
+			if (ex.get() != null) {
+				return ex.get();
+			}
+			else {
+				return new IllegalStateException("No default McpJsonMapper implementation found");
+			}
+		});
+	}
+
+	private static void addException(AtomicReference ref, Exception toAdd) {
+		ref.updateAndGet(existing -> {
+			if (existing == null) {
+				return new IllegalStateException("Failed to initialize default McpJsonMapper", toAdd);
+			}
+			else {
+				existing.addSuppressed(toAdd);
+				return existing;
+			}
+		});
+	}
+
+}
diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java
new file mode 100644
index 000000000..1e30cad16
--- /dev/null
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java
@@ -0,0 +1,110 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json;
+
+import java.io.IOException;
+
+/**
+ * Abstraction for JSON serialization/deserialization to decouple the SDK from any
+ * specific JSON library. A default implementation backed by Jackson is provided in
+ * io.modelcontextprotocol.spec.json.jackson.JacksonJsonMapper.
+ */
+public interface McpJsonMapper {
+
+	/**
+	 * Deserialize JSON string into a target type.
+	 * @param content JSON as String
+	 * @param type target class
+	 * @return deserialized instance
+	 * @param  generic type
+	 * @throws IOException on parse errors
+	 */
+	 T readValue(String content, Class type) throws IOException;
+
+	/**
+	 * Deserialize JSON bytes into a target type.
+	 * @param content JSON as bytes
+	 * @param type target class
+	 * @return deserialized instance
+	 * @param  generic type
+	 * @throws IOException on parse errors
+	 */
+	 T readValue(byte[] content, Class type) throws IOException;
+
+	/**
+	 * Deserialize JSON string into a parameterized target type.
+	 * @param content JSON as String
+	 * @param type parameterized type reference
+	 * @return deserialized instance
+	 * @param  generic type
+	 * @throws IOException on parse errors
+	 */
+	 T readValue(String content, TypeRef type) throws IOException;
+
+	/**
+	 * Deserialize JSON bytes into a parameterized target type.
+	 * @param content JSON as bytes
+	 * @param type parameterized type reference
+	 * @return deserialized instance
+	 * @param  generic type
+	 * @throws IOException on parse errors
+	 */
+	 T readValue(byte[] content, TypeRef type) throws IOException;
+
+	/**
+	 * Convert a value to a given type, useful for mapping nested JSON structures.
+	 * @param fromValue source value
+	 * @param type target class
+	 * @return converted value
+	 * @param  generic type
+	 */
+	 T convertValue(Object fromValue, Class type);
+
+	/**
+	 * Convert a value to a given parameterized type.
+	 * @param fromValue source value
+	 * @param type target type reference
+	 * @return converted value
+	 * @param  generic type
+	 */
+	 T convertValue(Object fromValue, TypeRef type);
+
+	/**
+	 * Serialize an object to JSON string.
+	 * @param value object to serialize
+	 * @return JSON as String
+	 * @throws IOException on serialization errors
+	 */
+	String writeValueAsString(Object value) throws IOException;
+
+	/**
+	 * Serialize an object to JSON bytes.
+	 * @param value object to serialize
+	 * @return JSON as bytes
+	 * @throws IOException on serialization errors
+	 */
+	byte[] writeValueAsBytes(Object value) throws IOException;
+
+	/**
+	 * Returns the default {@link McpJsonMapper}.
+	 * @return The default {@link McpJsonMapper}
+	 * @throws IllegalStateException If no {@link McpJsonMapper} implementation exists on
+	 * the classpath.
+	 */
+	static McpJsonMapper getDefault() {
+		return McpJsonInternal.getDefaultMapper();
+	}
+
+	/**
+	 * Creates a new default {@link McpJsonMapper}.
+	 * @return The default {@link McpJsonMapper}
+	 * @throws IllegalStateException If no {@link McpJsonMapper} implementation exists on
+	 * the classpath.
+	 */
+	static McpJsonMapper createDefault() {
+		return McpJsonInternal.createDefaultMapper();
+	}
+
+}
diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapperSupplier.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapperSupplier.java
new file mode 100644
index 000000000..619f96040
--- /dev/null
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/McpJsonMapperSupplier.java
@@ -0,0 +1,14 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json;
+
+import java.util.function.Supplier;
+
+/**
+ * Strategy interface for resolving a {@link McpJsonMapper}.
+ */
+public interface McpJsonMapperSupplier extends Supplier {
+
+}
diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java
new file mode 100644
index 000000000..725513c66
--- /dev/null
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json;
+
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+
+/**
+ * Captures generic type information at runtime for parameterized JSON (de)serialization.
+ * Usage: TypeRef> ref = new TypeRef<>(){};
+ */
+public abstract class TypeRef {
+
+	private final Type type;
+
+	/**
+	 * Constructs a new TypeRef instance, capturing the generic type information of the
+	 * subclass. This constructor should be called from an anonymous subclass to capture
+	 * the actual type arguments. For example: 
+	 * TypeRef<List<Foo>> ref = new TypeRef<>(){};
+	 * 

+	 * @throws IllegalStateException if TypeRef is not subclassed with actual type
+	 * information
+	 */
+	protected TypeRef() {
+		Type superClass = getClass().getGenericSuperclass();
+		if (superClass instanceof Class) {
+			throw new IllegalStateException("TypeRef constructed without actual type information");
+		}
+		this.type = ((ParameterizedType) superClass).getActualTypeArguments()[0];
+	}
+
+	/**
+	 * Returns the captured type information.
+	 * @return the Type representing the actual type argument captured by this TypeRef
+	 * instance
+	 */
+	public Type getType() {
+		return type;
+	}
+
+}
diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaInternal.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaInternal.java
new file mode 100644
index 000000000..2497e7f80
--- /dev/null
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaInternal.java
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json.schema;
+
+import java.util.ServiceLoader;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.stream.Stream;
+
+/**
+ * Internal utility class for creating a default {@link JsonSchemaValidator} instance.
+ * This class uses the {@link ServiceLoader} to discover and instantiate a
+ * {@link JsonSchemaValidatorSupplier} implementation.
+ */
+final class JsonSchemaInternal {
+
+	private static JsonSchemaValidator defaultValidator = null;
+
+	/**
+	 * Returns the default {@link JsonSchemaValidator} instance. If the default validator
+	 * has not been initialized, it will be created using the {@link ServiceLoader} to
+	 * discover and instantiate a {@link JsonSchemaValidatorSupplier} implementation.
+	 * @return The default {@link JsonSchemaValidator} instance.
+	 * @throws IllegalStateException If no {@link JsonSchemaValidatorSupplier}
+	 * implementation exists on the classpath or if an error occurs during instantiation.
+	 */
+	static JsonSchemaValidator getDefaultValidator() {
+		if (defaultValidator == null) {
+			defaultValidator = JsonSchemaInternal.createDefaultValidator();
+		}
+		return defaultValidator;
+	}
+
+	/**
+	 * Creates a default {@link JsonSchemaValidator} instance by loading a
+	 * {@link JsonSchemaValidatorSupplier} implementation using the {@link ServiceLoader}.
+	 * @return A default {@link JsonSchemaValidator} instance.
+	 * @throws IllegalStateException If no {@link JsonSchemaValidatorSupplier}
+	 * implementation is found or if an error occurs during instantiation.
+	 */
+	static JsonSchemaValidator createDefaultValidator() {
+		AtomicReference ex = new AtomicReference<>();
+		return ServiceLoader.load(JsonSchemaValidatorSupplier.class).stream().flatMap(p -> {
+			try {
+				JsonSchemaValidatorSupplier supplier = p.get();
+				return Stream.ofNullable(supplier);
+			}
+			catch (Exception e) {
+				addException(ex, e);
+				return Stream.empty();
+			}
+		}).flatMap(jsonMapperSupplier -> {
+			try {
+				return Stream.of(jsonMapperSupplier.get());
+			}
+			catch (Exception e) {
+				addException(ex, e);
+				return Stream.empty();
+			}
+		}).findFirst().orElseThrow(() -> {
+			if (ex.get() != null) {
+				return ex.get();
+			}
+			else {
+				return new IllegalStateException("No default JsonSchemaValidatorSupplier implementation found");
+			}
+		});
+	}
+
+	private static void addException(AtomicReference ref, Exception toAdd) {
+		ref.updateAndGet(existing -> {
+			if (existing == null) {
+				return new IllegalStateException("Failed to initialize default JsonSchemaValidatorSupplier", toAdd);
+			}
+			else {
+				existing.addSuppressed(toAdd);
+				return existing;
+			}
+		});
+	}
+
+}
diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidator.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidator.java
new file mode 100644
index 000000000..8e35c0237
--- /dev/null
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidator.java
@@ -0,0 +1,64 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+package io.modelcontextprotocol.json.schema;
+
+import java.util.Map;
+
+/**
+ * Interface for validating structured content against a JSON schema. This interface
+ * defines a method to validate structured content based on the provided output schema.
+ *
+ * @author Christian Tzolov
+ */
+public interface JsonSchemaValidator {
+
+	/**
+	 * Represents the result of a validation operation.
+	 *
+	 * @param valid Indicates whether the validation was successful.
+	 * @param errorMessage An error message if the validation failed, otherwise null.
+	 * @param jsonStructuredOutput The text structured content in JSON format if the
+	 * validation was successful, otherwise null.
+	 */
+	record ValidationResponse(boolean valid, String errorMessage, String jsonStructuredOutput) {
+
+		public static ValidationResponse asValid(String jsonStructuredOutput) {
+			return new ValidationResponse(true, null, jsonStructuredOutput);
+		}
+
+		public static ValidationResponse asInvalid(String message) {
+			return new ValidationResponse(false, message, null);
+		}
+	}
+
+	/**
+	 * Validates the structured content against the provided JSON schema.
+	 * @param schema The JSON schema to validate against.
+	 * @param structuredContent The structured content to validate.
+	 * @return A ValidationResponse indicating whether the validation was successful or
+	 * not.
+	 */
+	ValidationResponse validate(Map schema, Object structuredContent);
+
+	/**
+	 * Creates the default {@link JsonSchemaValidator}.
+	 * @return The default {@link JsonSchemaValidator}
+	 * @throws IllegalStateException If no {@link JsonSchemaValidator} implementation
+	 * exists on the classpath.
+	 */
+	static JsonSchemaValidator createDefault() {
+		return JsonSchemaInternal.createDefaultValidator();
+	}
+
+	/**
+	 * Returns the default {@link JsonSchemaValidator}.
+	 * @return The default {@link JsonSchemaValidator}
+	 * @throws IllegalStateException If no {@link JsonSchemaValidator} implementation
+	 * exists on the classpath.
+	 */
+	static JsonSchemaValidator getDefault() {
+		return JsonSchemaInternal.getDefaultValidator();
+	}
+
+}
diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidatorSupplier.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidatorSupplier.java
new file mode 100644
index 000000000..6f69169a0
--- /dev/null
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidatorSupplier.java
@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json.schema;
+
+import java.util.function.Supplier;
+
+/**
+ * A supplier interface that provides a {@link JsonSchemaValidator} instance.
+ * Implementations of this interface are expected to return a new or cached instance of
+ * {@link JsonSchemaValidator} when {@link #get()} is invoked.
+ *
+ * @see JsonSchemaValidator
+ * @see Supplier
+ */
+public interface JsonSchemaValidatorSupplier extends Supplier {
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index c2dac2bf9..eda38881a 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -22,7 +22,13 @@
 	
 
 	
-		
+        
+            io.modelcontextprotocol.sdk
+            mcp-json-jackson2
+            0.13.0-SNAPSHOT
+        
+
+        
 			io.modelcontextprotocol.sdk
 			mcp
 			0.13.0-SNAPSHOT
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 853aed2bf..154eb4703 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -22,8 +22,8 @@
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.client.WebClientResponseException;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
+import io.modelcontextprotocol.json.McpJsonMapper;
 
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
@@ -88,7 +88,7 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 	private static final ParameterizedTypeReference> PARAMETERIZED_TYPE_REF = new ParameterizedTypeReference<>() {
 	};
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final WebClient webClient;
 
@@ -104,9 +104,9 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 
 	private final AtomicReference> exceptionHandler = new AtomicReference<>();
 
-	private WebClientStreamableHttpTransport(ObjectMapper objectMapper, WebClient.Builder webClientBuilder,
+	private WebClientStreamableHttpTransport(McpJsonMapper jsonMapper, WebClient.Builder webClientBuilder,
 			String endpoint, boolean resumableStreams, boolean openConnectionOnStartup) {
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.webClient = webClientBuilder.build();
 		this.endpoint = endpoint;
 		this.resumableStreams = resumableStreams;
@@ -366,8 +366,7 @@ private Flux extractError(ClientResponse response, Str
 			McpSchema.JSONRPCResponse.JSONRPCError jsonRpcError = null;
 			Exception toPropagate;
 			try {
-				McpSchema.JSONRPCResponse jsonRpcResponse = objectMapper.readValue(body,
-						McpSchema.JSONRPCResponse.class);
+				McpSchema.JSONRPCResponse jsonRpcResponse = jsonMapper.readValue(body, McpSchema.JSONRPCResponse.class);
 				jsonRpcError = jsonRpcResponse.error();
 				toPropagate = jsonRpcError != null ? new McpError(jsonRpcError)
 						: new McpTransportException("Can't parse the jsonResponse " + jsonRpcResponse);
@@ -427,7 +426,7 @@ private Flux directResponseFlux(McpSchema.JSONRPCMessa
 					s.complete();
 				}
 				else {
-					McpSchema.JSONRPCMessage jsonRpcResponse = McpSchema.deserializeJsonRpcMessage(objectMapper,
+					McpSchema.JSONRPCMessage jsonRpcResponse = McpSchema.deserializeJsonRpcMessage(jsonMapper,
 							responseMessage);
 					s.next(List.of(jsonRpcResponse));
 				}
@@ -447,8 +446,8 @@ private Flux newEventStream(ClientResponse response, S
 	}
 
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return this.objectMapper.convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return this.jsonMapper.convertValue(data, typeRef);
 	}
 
 	private Tuple2, Iterable> parse(ServerSentEvent event) {
@@ -456,7 +455,7 @@ private Tuple2, Iterable> parse(Serve
 			try {
 				// We don't support batching ATM and probably won't since the next version
 				// considers removing it.
-				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(this.objectMapper, event.data());
+				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(this.jsonMapper, event.data());
 				return Tuples.of(Optional.ofNullable(event.id()), List.of(message));
 			}
 			catch (IOException ioException) {
@@ -474,7 +473,7 @@ private Tuple2, Iterable> parse(Serve
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private WebClient.Builder webClientBuilder;
 
@@ -490,13 +489,13 @@ private Builder(WebClient.Builder webClientBuilder) {
 		}
 
 		/**
-		 * Configure the {@link ObjectMapper} to use.
-		 * @param objectMapper instance to use
+		 * Configure the {@link McpJsonMapper} to use.
+		 * @param jsonMapper instance to use
 		 * @return the builder instance
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -555,10 +554,8 @@ public Builder openConnectionOnStartup(boolean openConnectionOnStartup) {
 		 * @return a new instance of {@link WebClientStreamableHttpTransport}
 		 */
 		public WebClientStreamableHttpTransport build() {
-			ObjectMapper objectMapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
-
-			return new WebClientStreamableHttpTransport(objectMapper, this.webClientBuilder, endpoint, resumableStreams,
-					openConnectionOnStartup);
+			return new WebClientStreamableHttpTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					webClientBuilder, endpoint, resumableStreams, openConnectionOnStartup);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
index 51d21d18b..91b89d6d2 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransport.java
@@ -9,8 +9,8 @@
 import java.util.function.BiConsumer;
 import java.util.function.Function;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
@@ -100,10 +100,10 @@ public class WebFluxSseClientTransport implements McpClientTransport {
 	private final WebClient webClient;
 
 	/**
-	 * ObjectMapper for serializing outbound messages and deserializing inbound messages.
+	 * JSON mapper for serializing outbound messages and deserializing inbound messages.
 	 * Handles conversion between JSON-RPC messages and their string representation.
 	 */
-	protected ObjectMapper objectMapper;
+	protected McpJsonMapper jsonMapper;
 
 	/**
 	 * Subscription for the SSE connection handling inbound messages. Used for cleanup
@@ -129,27 +129,16 @@ public class WebFluxSseClientTransport implements McpClientTransport {
 	 */
 	private String sseEndpoint;
 
-	/**
-	 * Constructs a new SseClientTransport with the specified WebClient builder. Uses a
-	 * default ObjectMapper instance for JSON processing.
-	 * @param webClientBuilder the WebClient.Builder to use for creating the WebClient
-	 * instance
-	 * @throws IllegalArgumentException if webClientBuilder is null
-	 */
-	public WebFluxSseClientTransport(WebClient.Builder webClientBuilder) {
-		this(webClientBuilder, new ObjectMapper());
-	}
-
 	/**
 	 * Constructs a new SseClientTransport with the specified WebClient builder and
 	 * ObjectMapper. Initializes both inbound and outbound message processing pipelines.
 	 * @param webClientBuilder the WebClient.Builder to use for creating the WebClient
 	 * instance
-	 * @param objectMapper the ObjectMapper to use for JSON processing
+	 * @param jsonMapper the ObjectMapper to use for JSON processing
 	 * @throws IllegalArgumentException if either parameter is null
 	 */
-	public WebFluxSseClientTransport(WebClient.Builder webClientBuilder, ObjectMapper objectMapper) {
-		this(webClientBuilder, objectMapper, DEFAULT_SSE_ENDPOINT);
+	public WebFluxSseClientTransport(WebClient.Builder webClientBuilder, McpJsonMapper jsonMapper) {
+		this(webClientBuilder, jsonMapper, DEFAULT_SSE_ENDPOINT);
 	}
 
 	/**
@@ -157,17 +146,16 @@ public WebFluxSseClientTransport(WebClient.Builder webClientBuilder, ObjectMappe
 	 * ObjectMapper. Initializes both inbound and outbound message processing pipelines.
 	 * @param webClientBuilder the WebClient.Builder to use for creating the WebClient
 	 * instance
-	 * @param objectMapper the ObjectMapper to use for JSON processing
+	 * @param jsonMapper the ObjectMapper to use for JSON processing
 	 * @param sseEndpoint the SSE endpoint URI to use for establishing the connection
 	 * @throws IllegalArgumentException if either parameter is null
 	 */
-	public WebFluxSseClientTransport(WebClient.Builder webClientBuilder, ObjectMapper objectMapper,
-			String sseEndpoint) {
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+	public WebFluxSseClientTransport(WebClient.Builder webClientBuilder, McpJsonMapper jsonMapper, String sseEndpoint) {
+		Assert.notNull(jsonMapper, "jsonMapper must not be null");
 		Assert.notNull(webClientBuilder, "WebClient.Builder must not be null");
 		Assert.hasText(sseEndpoint, "SSE endpoint must not be null or empty");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.webClient = webClientBuilder.build();
 		this.sseEndpoint = sseEndpoint;
 	}
@@ -217,7 +205,7 @@ public Mono connect(Function, Mono> h
 			}
 			else if (MESSAGE_EVENT_TYPE.equals(event.event())) {
 				try {
-					JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(this.objectMapper, event.data());
+					JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(this.jsonMapper, event.data());
 					s.next(message);
 				}
 				catch (IOException ioException) {
@@ -255,7 +243,7 @@ public Mono sendMessage(JSONRPCMessage message) {
 				return Mono.empty();
 			}
 			try {
-				String jsonText = this.objectMapper.writeValueAsString(message);
+				String jsonText = this.jsonMapper.writeValueAsString(message);
 				return webClient.post()
 					.uri(messageEndpointUri)
 					.contentType(MediaType.APPLICATION_JSON)
@@ -349,13 +337,13 @@ public Mono closeGracefully() { // @formatter:off
 	 * type conversion capabilities to handle complex object structures.
 	 * @param  the target type to convert the data into
 	 * @param data the source object to convert
-	 * @param typeRef the TypeReference describing the target type
+	 * @param typeRef the TypeRef describing the target type
 	 * @return the unmarshalled object of type T
 	 * @throws IllegalArgumentException if the conversion cannot be performed
 	 */
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return this.objectMapper.convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return this.jsonMapper.convertValue(data, typeRef);
 	}
 
 	/**
@@ -377,7 +365,7 @@ public static class Builder {
 
 		private String sseEndpoint = DEFAULT_SSE_ENDPOINT;
 
-		private ObjectMapper objectMapper = new ObjectMapper();
+		private McpJsonMapper jsonMapper;
 
 		/**
 		 * Creates a new builder with the specified WebClient.Builder.
@@ -400,13 +388,13 @@ public Builder sseEndpoint(String sseEndpoint) {
 		}
 
 		/**
-		 * Sets the object mapper for JSON serialization/deserialization.
-		 * @param objectMapper the object mapper
+		 * Sets the JSON mapper for serialization/deserialization.
+		 * @param jsonMapper the JsonMapper to use
 		 * @return this builder
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "objectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "jsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -415,7 +403,8 @@ public Builder objectMapper(ObjectMapper objectMapper) {
 		 * @return a new transport instance
 		 */
 		public WebFluxSseClientTransport build() {
-			return new WebFluxSseClientTransport(webClientBuilder, objectMapper, sseEndpoint);
+			return new WebFluxSseClientTransport(webClientBuilder,
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, sseEndpoint);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index f64346265..95355c0f2 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -9,8 +9,8 @@
 import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
@@ -97,7 +97,7 @@ public class WebFluxSseServerTransportProvider implements McpServerTransportProv
 
 	public static final String DEFAULT_BASE_URL = "";
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	/**
 	 * Base URL for the message endpoint. This is used to construct the full URL for
@@ -131,82 +131,10 @@ public class WebFluxSseServerTransportProvider implements McpServerTransportProv
 	 */
 	private KeepAliveScheduler keepAliveScheduler;
 
-	/**
-	 * Constructs a new WebFlux SSE server transport provider instance with the default
-	 * SSE endpoint.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of MCP messages. Must not be null.
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages. This endpoint will be communicated to clients during SSE connection
-	 * setup. Must not be null.
-	 * @throws IllegalArgumentException if either parameter is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint) {
-		this(objectMapper, messageEndpoint, DEFAULT_SSE_ENDPOINT);
-	}
-
-	/**
-	 * Constructs a new WebFlux SSE server transport provider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of MCP messages. Must not be null.
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages. This endpoint will be communicated to clients during SSE connection
-	 * setup. Must not be null.
-	 * @throws IllegalArgumentException if either parameter is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint) {
-		this(objectMapper, DEFAULT_BASE_URL, messageEndpoint, sseEndpoint);
-	}
-
-	/**
-	 * Constructs a new WebFlux SSE server transport provider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of MCP messages. Must not be null.
-	 * @param baseUrl webflux message base path
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages. This endpoint will be communicated to clients during SSE connection
-	 * setup. Must not be null.
-	 * @throws IllegalArgumentException if either parameter is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
-			String sseEndpoint) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null);
-	}
-
-	/**
-	 * Constructs a new WebFlux SSE server transport provider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of MCP messages. Must not be null.
-	 * @param baseUrl webflux message base path
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages. This endpoint will be communicated to clients during SSE connection
-	 * setup. Must not be null.
-	 * @param sseEndpoint The SSE endpoint path. Must not be null.
-	 * @param keepAliveInterval The interval for sending keep-alive pings to clients.
-	 * @throws IllegalArgumentException if either parameter is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
-			String sseEndpoint, Duration keepAliveInterval) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
-				(serverRequest) -> McpTransportContext.EMPTY);
-	}
-
 	/**
 	 * Constructs a new WebFlux SSE server transport provider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of MCP messages. Must not be null.
+	 * @param jsonMapper The ObjectMapper to use for JSON serialization/deserialization of
+	 * MCP messages. Must not be null.
 	 * @param baseUrl webflux message base path
 	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
 	 * messages. This endpoint will be communicated to clients during SSE connection
@@ -217,16 +145,16 @@ public WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseU
 	 * context from HTTP requests. Must not be null.
 	 * @throws IllegalArgumentException if either parameter is null
 	 */
-	private WebFluxSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+	private WebFluxSseServerTransportProvider(McpJsonMapper jsonMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval,
 			McpTransportContextExtractor contextExtractor) {
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(jsonMapper, "ObjectMapper must not be null");
 		Assert.notNull(baseUrl, "Message base path must not be null");
 		Assert.notNull(messageEndpoint, "Message endpoint must not be null");
 		Assert.notNull(sseEndpoint, "SSE endpoint must not be null");
 		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.baseUrl = baseUrl;
 		this.messageEndpoint = messageEndpoint;
 		this.sseEndpoint = sseEndpoint;
@@ -404,7 +332,7 @@ private Mono handleMessage(ServerRequest request) {
 
 		return request.bodyToMono(String.class).flatMap(body -> {
 			try {
-				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 				return session.handle(message).flatMap(response -> ServerResponse.ok().build()).onErrorResume(error -> {
 					logger.error("Error processing  message: {}", error.getMessage());
 					// TODO: instead of signalling the error, just respond with 200 OK
@@ -433,7 +361,7 @@ public WebFluxMcpSessionTransport(FluxSink> sink) {
 		public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			return Mono.fromSupplier(() -> {
 				try {
-					return objectMapper.writeValueAsString(message);
+					return jsonMapper.writeValueAsString(message);
 				}
 				catch (IOException e) {
 					throw Exceptions.propagate(e);
@@ -452,8 +380,8 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 		}
 
 		@Override
-		public  T unmarshalFrom(Object data, TypeReference typeRef) {
-			return objectMapper.convertValue(data, typeRef);
+		public  T unmarshalFrom(Object data, TypeRef typeRef) {
+			return jsonMapper.convertValue(data, typeRef);
 		}
 
 		@Override
@@ -480,7 +408,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private String baseUrl = DEFAULT_BASE_URL;
 
@@ -494,15 +422,15 @@ public static class Builder {
 				serverRequest) -> McpTransportContext.EMPTY;
 
 		/**
-		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * Sets the McpJsonMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
-		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @param jsonMapper The McpJsonMapper instance. Must not be null.
 		 * @return this builder instance
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -577,11 +505,9 @@ public Builder contextExtractor(McpTransportContextExtractor cont
 		 * @throws IllegalStateException if required parameters are not set
 		 */
 		public WebFluxSseServerTransportProvider build() {
-			Assert.notNull(objectMapper, "ObjectMapper must be set");
 			Assert.notNull(messageEndpoint, "Message endpoint must be set");
-
-			return new WebFluxSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
-					keepAliveInterval, contextExtractor);
+			return new WebFluxSseServerTransportProvider(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval, contextExtractor);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
index 1f3d4c3bf..400be341e 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStatelessServerTransport.java
@@ -4,7 +4,7 @@
 
 package io.modelcontextprotocol.server.transport;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
@@ -34,7 +34,7 @@ public class WebFluxStatelessServerTransport implements McpStatelessServerTransp
 
 	private static final Logger logger = LoggerFactory.getLogger(WebFluxStatelessServerTransport.class);
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final String mcpEndpoint;
 
@@ -46,13 +46,13 @@ public class WebFluxStatelessServerTransport implements McpStatelessServerTransp
 
 	private volatile boolean isClosing = false;
 
-	private WebFluxStatelessServerTransport(ObjectMapper objectMapper, String mcpEndpoint,
+	private WebFluxStatelessServerTransport(McpJsonMapper jsonMapper, String mcpEndpoint,
 			McpTransportContextExtractor contextExtractor) {
-		Assert.notNull(objectMapper, "objectMapper must not be null");
+		Assert.notNull(jsonMapper, "jsonMapper must not be null");
 		Assert.notNull(mcpEndpoint, "mcpEndpoint must not be null");
 		Assert.notNull(contextExtractor, "contextExtractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.mcpEndpoint = mcpEndpoint;
 		this.contextExtractor = contextExtractor;
 		this.routerFunction = RouterFunctions.route()
@@ -106,13 +106,20 @@ private Mono handlePost(ServerRequest request) {
 
 		return request.bodyToMono(String.class).flatMap(body -> {
 			try {
-				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 
 				if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
-					return this.mcpHandler.handleRequest(transportContext, jsonrpcRequest)
-						.flatMap(jsonrpcResponse -> ServerResponse.ok()
-							.contentType(MediaType.APPLICATION_JSON)
-							.bodyValue(jsonrpcResponse));
+					return this.mcpHandler.handleRequest(transportContext, jsonrpcRequest).flatMap(jsonrpcResponse -> {
+						try {
+							String json = jsonMapper.writeValueAsString(jsonrpcResponse);
+							return ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).bodyValue(json);
+						}
+						catch (IOException e) {
+							logger.error("Failed to serialize response: {}", e.getMessage());
+							return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
+								.bodyValue(new McpError("Failed to serialize response"));
+						}
+					});
 				}
 				else if (message instanceof McpSchema.JSONRPCNotification jsonrpcNotification) {
 					return this.mcpHandler.handleNotification(transportContext, jsonrpcNotification)
@@ -146,7 +153,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private String mcpEndpoint = "/mcp";
 
@@ -158,15 +165,15 @@ private Builder() {
 		}
 
 		/**
-		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * Sets the JsonMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
-		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @param jsonMapper The JsonMapper instance. Must not be null.
 		 * @return this builder instance
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -205,10 +212,9 @@ public Builder contextExtractor(McpTransportContextExtractor cont
 		 * @throws IllegalStateException if required parameters are not set
 		 */
 		public WebFluxStatelessServerTransport build() {
-			Assert.notNull(objectMapper, "ObjectMapper must be set");
 			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
-
-			return new WebFluxStatelessServerTransport(objectMapper, mcpEndpoint, contextExtractor);
+			return new WebFluxStatelessServerTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					mcpEndpoint, contextExtractor);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index 44d89eaeb..b6cc20864 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -4,8 +4,8 @@
 
 package io.modelcontextprotocol.server.transport;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.HttpHeaders;
@@ -49,7 +49,7 @@ public class WebFluxStreamableServerTransportProvider implements McpStreamableSe
 
 	public static final String MESSAGE_EVENT_TYPE = "message";
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final String mcpEndpoint;
 
@@ -67,14 +67,14 @@ public class WebFluxStreamableServerTransportProvider implements McpStreamableSe
 
 	private KeepAliveScheduler keepAliveScheduler;
 
-	private WebFluxStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
+	private WebFluxStreamableServerTransportProvider(McpJsonMapper jsonMapper, String mcpEndpoint,
 			McpTransportContextExtractor contextExtractor, boolean disallowDelete,
 			Duration keepAliveInterval) {
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(jsonMapper, "JsonMapper must not be null");
 		Assert.notNull(mcpEndpoint, "Message endpoint must not be null");
 		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.mcpEndpoint = mcpEndpoint;
 		this.contextExtractor = contextExtractor;
 		this.disallowDelete = disallowDelete;
@@ -230,12 +230,13 @@ private Mono handlePost(ServerRequest request) {
 
 		return request.bodyToMono(String.class).flatMap(body -> {
 			try {
-				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+				McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 				if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest
 						&& jsonrpcRequest.method().equals(McpSchema.METHOD_INITIALIZE)) {
-					McpSchema.InitializeRequest initializeRequest = objectMapper.convertValue(jsonrpcRequest.params(),
-							new TypeReference() {
-							});
+					var typeReference = new TypeRef() {
+					};
+					McpSchema.InitializeRequest initializeRequest = jsonMapper.convertValue(jsonrpcRequest.params(),
+							typeReference);
 					McpStreamableServerSession.McpStreamableServerSessionInit init = this.sessionFactory
 						.startSession(initializeRequest);
 					sessions.put(init.session().getId(), init.session());
@@ -243,7 +244,7 @@ private Mono handlePost(ServerRequest request) {
 						McpSchema.JSONRPCResponse jsonrpcResponse = new McpSchema.JSONRPCResponse(
 								McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), initializeResult, null);
 						try {
-							return this.objectMapper.writeValueAsString(jsonrpcResponse);
+							return this.jsonMapper.writeValueAsString(jsonrpcResponse);
 						}
 						catch (IOException e) {
 							logger.warn("Failed to serialize initResponse", e);
@@ -349,7 +350,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 		public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId) {
 			return Mono.fromSupplier(() -> {
 				try {
-					return objectMapper.writeValueAsString(message);
+					return jsonMapper.writeValueAsString(message);
 				}
 				catch (IOException e) {
 					throw Exceptions.propagate(e);
@@ -369,8 +370,8 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId
 		}
 
 		@Override
-		public  T unmarshalFrom(Object data, TypeReference typeRef) {
-			return objectMapper.convertValue(data, typeRef);
+		public  T unmarshalFrom(Object data, TypeRef typeRef) {
+			return jsonMapper.convertValue(data, typeRef);
 		}
 
 		@Override
@@ -397,7 +398,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private String mcpEndpoint = "/mcp";
 
@@ -413,15 +414,15 @@ private Builder() {
 		}
 
 		/**
-		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
-		 * messages.
-		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * Sets the {@link McpJsonMapper} to use for JSON serialization/deserialization of
+		 * MCP messages.
+		 * @param jsonMapper The {@link McpJsonMapper} instance. Must not be null.
 		 * @return this builder instance
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "McpJsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -482,13 +483,12 @@ public Builder keepAliveInterval(Duration keepAliveInterval) {
 		 * @throws IllegalStateException if required parameters are not set
 		 */
 		public WebFluxStreamableServerTransportProvider build() {
-			Assert.notNull(objectMapper, "ObjectMapper must be set");
 			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
-
-			return new WebFluxStreamableServerTransportProvider(objectMapper, mcpEndpoint, contextExtractor,
+			return new WebFluxStreamableServerTransportProvider(
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, mcpEndpoint, contextExtractor,
 					disallowDelete, keepAliveInterval);
 		}
 
 	}
 
-}
\ No newline at end of file
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index f8f0f7a3a..f580b59e8 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -16,8 +16,6 @@
 import org.springframework.web.reactive.function.server.RouterFunctions;
 import org.springframework.web.reactive.function.server.ServerRequest;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
@@ -79,7 +77,6 @@ protected SingleSessionSyncSpecification prepareSyncServerBuilder() {
 	public void before() {
 
 		this.mcpServerTransportProvider = new WebFluxSseServerTransportProvider.Builder()
-			.objectMapper(new ObjectMapper())
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
 			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
index 5516e55b7..a00e24b55 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
@@ -13,9 +13,6 @@
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.server.RouterFunctions;
-
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
@@ -67,7 +64,6 @@ protected StatelessSyncSpecification prepareSyncServerBuilder() {
 	@BeforeEach
 	public void before() {
 		this.mcpStreamableServerTransport = WebFluxStatelessServerTransport.builder()
-			.objectMapper(new ObjectMapper())
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.build();
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
index 933ddf39d..e4bcef829 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -16,8 +16,6 @@
 import org.springframework.web.reactive.function.server.RouterFunctions;
 import org.springframework.web.reactive.function.server.ServerRequest;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
@@ -76,7 +74,6 @@ protected SyncSpecification prepareSyncServerBuilder() {
 	public void before() {
 
 		this.mcpStreamableServerTransportProvider = WebFluxStreamableServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 			.build();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
index 804feb135..0f35f9f0d 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
@@ -13,7 +13,6 @@
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
-
 import org.springframework.web.reactive.function.client.WebClient;
 
 /**
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
index 06c95d145..3dacb62d8 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
@@ -11,6 +11,8 @@
 import java.util.function.Function;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.jackson.JacksonMcpJsonMapper;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCRequest;
 import org.junit.jupiter.api.AfterAll;
@@ -29,6 +31,7 @@
 import org.springframework.http.codec.ServerSentEvent;
 import org.springframework.web.reactive.function.client.WebClient;
 
+import static io.modelcontextprotocol.utils.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -54,8 +57,6 @@ class WebFluxSseClientTransportTests {
 
 	private WebClient.Builder webClientBuilder;
 
-	private ObjectMapper objectMapper;
-
 	// Test class to access protected methods
 	static class TestSseClientTransport extends WebFluxSseClientTransport {
 
@@ -63,8 +64,8 @@ static class TestSseClientTransport extends WebFluxSseClientTransport {
 
 		private Sinks.Many> events = Sinks.many().unicast().onBackpressureBuffer();
 
-		public TestSseClientTransport(WebClient.Builder webClientBuilder, ObjectMapper objectMapper) {
-			super(webClientBuilder, objectMapper);
+		public TestSseClientTransport(WebClient.Builder webClientBuilder, McpJsonMapper jsonMapper) {
+			super(webClientBuilder, jsonMapper);
 		}
 
 		@Override
@@ -112,8 +113,7 @@ static void cleanup() {
 	@BeforeEach
 	void setUp() {
 		webClientBuilder = WebClient.builder().baseUrl(host);
-		objectMapper = new ObjectMapper();
-		transport = new TestSseClientTransport(webClientBuilder, objectMapper);
+		transport = new TestSseClientTransport(webClientBuilder, JSON_MAPPER);
 		transport.connect(Function.identity()).block();
 	}
 
@@ -131,12 +131,13 @@ void testEndpointEventHandling() {
 
 	@Test
 	void constructorValidation() {
-		assertThatThrownBy(() -> new WebFluxSseClientTransport(null)).isInstanceOf(IllegalArgumentException.class)
+		assertThatThrownBy(() -> new WebFluxSseClientTransport(null, JSON_MAPPER))
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("WebClient.Builder must not be null");
 
 		assertThatThrownBy(() -> new WebFluxSseClientTransport(webClientBuilder, null))
 			.isInstanceOf(IllegalArgumentException.class)
-			.hasMessageContaining("ObjectMapper must not be null");
+			.hasMessageContaining("jsonMapper must not be null");
 	}
 
 	@Test
@@ -148,7 +149,7 @@ void testBuilderPattern() {
 		// Test builder with custom ObjectMapper
 		ObjectMapper customMapper = new ObjectMapper();
 		WebFluxSseClientTransport transport2 = WebFluxSseClientTransport.builder(webClientBuilder)
-			.objectMapper(customMapper)
+			.jsonMapper(new JacksonMcpJsonMapper(customMapper))
 			.build();
 		assertThatCode(() -> transport2.closeGracefully().block()).doesNotThrowAnyException();
 
@@ -160,7 +161,6 @@ void testBuilderPattern() {
 
 		// Test builder with all custom parameters
 		WebFluxSseClientTransport transport4 = WebFluxSseClientTransport.builder(webClientBuilder)
-			.objectMapper(customMapper)
 			.sseEndpoint("/custom-sse")
 			.build();
 		assertThatCode(() -> transport4.closeGracefully().block()).doesNotThrowAnyException();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
index f3e2d3626..3db0bbd3a 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
@@ -7,7 +7,6 @@
 import java.util.Map;
 import java.util.function.BiFunction;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpAsyncClient;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
@@ -110,18 +109,15 @@ public class AsyncServerMcpTransportContextIntegrationTests {
 
 	// Server transports
 	private final WebFluxStatelessServerTransport statelessServerTransport = WebFluxStatelessServerTransport.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final WebFluxStreamableServerTransportProvider streamableServerTransport = WebFluxStreamableServerTransportProvider
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final WebFluxSseServerTransportProvider sseServerTransport = WebFluxSseServerTransportProvider.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.messageEndpoint("/mcp/message")
 		.build();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
index 865192489..94e16e73e 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
@@ -8,7 +8,6 @@
 import java.util.function.BiFunction;
 import java.util.function.Supplier;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.McpSyncClient;
 import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
@@ -105,18 +104,15 @@ public class SyncServerMcpTransportContextIntegrationTests {
 	};
 
 	private final WebFluxStatelessServerTransport statelessServerTransport = WebFluxStatelessServerTransport.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final WebFluxStreamableServerTransportProvider streamableServerTransport = WebFluxStreamableServerTransportProvider
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final WebFluxSseServerTransportProvider sseServerTransport = WebFluxSseServerTransportProvider.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.messageEndpoint("/mcp/message")
 		.build();
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java
index a3bdf10b0..fe0314687 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpAsyncServerTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
@@ -30,8 +29,7 @@ class WebFluxSseMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
 	private DisposableServer httpServer;
 
 	private McpServerTransportProvider createMcpTransportProvider() {
-		var transportProvider = new WebFluxSseServerTransportProvider.Builder().objectMapper(new ObjectMapper())
-			.messageEndpoint(MESSAGE_ENDPOINT)
+		var transportProvider = new WebFluxSseServerTransportProvider.Builder().messageEndpoint(MESSAGE_ENDPOINT)
 			.build();
 
 		HttpHandler httpHandler = RouterFunctions.toHttpHandler(transportProvider.getRouterFunction());
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java
index 3e28e96b8..67ef90bdf 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxSseMcpSyncServerTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
@@ -37,9 +36,7 @@ protected McpServer.SyncSpecification prepareSyncServerBuilder() {
 	}
 
 	private McpServerTransportProvider createMcpTransportProvider() {
-		transportProvider = new WebFluxSseServerTransportProvider.Builder().objectMapper(new ObjectMapper())
-			.messageEndpoint(MESSAGE_ENDPOINT)
-			.build();
+		transportProvider = new WebFluxSseServerTransportProvider.Builder().messageEndpoint(MESSAGE_ENDPOINT).build();
 		return transportProvider;
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
index 959f2f472..9b5a80f16 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpAsyncServerTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
@@ -32,7 +31,6 @@ class WebFluxStreamableMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
 
 	private McpStreamableServerTransportProvider createMcpTransportProvider() {
 		var transportProvider = WebFluxStreamableServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
 			.messageEndpoint(MESSAGE_ENDPOINT)
 			.build();
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
index 3396d489c..6a47ba3ae 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/server/WebFluxStreamableMcpSyncServerTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
@@ -32,7 +31,6 @@ class WebFluxStreamableMcpSyncServerTests extends AbstractMcpSyncServerTests {
 
 	private McpStreamableServerTransportProvider createMcpTransportProvider() {
 		var transportProvider = WebFluxStreamableServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
 			.messageEndpoint(MESSAGE_ENDPOINT)
 			.build();
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
new file mode 100644
index 000000000..67347573c
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
@@ -0,0 +1,12 @@
+package io.modelcontextprotocol.utils;
+
+import io.modelcontextprotocol.json.McpJsonMapper;
+
+public final class McpJsonMapperUtils {
+
+	private McpJsonMapperUtils() {
+	}
+
+	public static final McpJsonMapper JSON_MAPPER = McpJsonMapper.createDefault();
+
+}
\ No newline at end of file
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 4bd9f87aa..8c698487d 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -22,7 +22,13 @@
 	
 
 	
-		
+        
+            io.modelcontextprotocol.sdk
+            mcp-json-jackson2
+            0.13.0-SNAPSHOT
+        
+
+        
 			io.modelcontextprotocol.sdk
 			mcp
 			0.13.0-SNAPSHOT
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index 85373b6fe..0b71ddc1f 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -11,8 +11,8 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
@@ -92,7 +92,7 @@ public class WebMvcSseServerTransportProvider implements McpServerTransportProvi
 	 */
 	public static final String DEFAULT_SSE_ENDPOINT = "/sse";
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final String messageEndpoint;
 
@@ -118,85 +118,9 @@ public class WebMvcSseServerTransportProvider implements McpServerTransportProvi
 
 	private KeepAliveScheduler keepAliveScheduler;
 
-	/**
-	 * Constructs a new WebMvcSseServerTransportProvider instance with the default SSE
-	 * endpoint.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of messages.
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages via HTTP POST. This endpoint will be communicated to clients through the
-	 * SSE connection's initial endpoint event.
-	 * @throws IllegalArgumentException if either objectMapper or messageEndpoint is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint) {
-		this(objectMapper, messageEndpoint, DEFAULT_SSE_ENDPOINT);
-	}
-
-	/**
-	 * Constructs a new WebMvcSseServerTransportProvider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of messages.
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages via HTTP POST. This endpoint will be communicated to clients through the
-	 * SSE connection's initial endpoint event.
-	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
-	 * @throws IllegalArgumentException if any parameter is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint, String sseEndpoint) {
-		this(objectMapper, "", messageEndpoint, sseEndpoint);
-	}
-
-	/**
-	 * Constructs a new WebMvcSseServerTransportProvider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of messages.
-	 * @param baseUrl The base URL for the message endpoint, used to construct the full
-	 * endpoint URL for clients.
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages via HTTP POST. This endpoint will be communicated to clients through the
-	 * SSE connection's initial endpoint event.
-	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
-	 * @throws IllegalArgumentException if any parameter is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
-			String sseEndpoint) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null);
-	}
-
-	/**
-	 * Constructs a new WebMvcSseServerTransportProvider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of messages.
-	 * @param baseUrl The base URL for the message endpoint, used to construct the full
-	 * endpoint URL for clients.
-	 * @param messageEndpoint The endpoint URI where clients should send their JSON-RPC
-	 * messages via HTTP POST. This endpoint will be communicated to clients through the
-	 * SSE connection's initial endpoint event.
-	 * @param sseEndpoint The endpoint URI where clients establish their SSE connections.
-	 * @param keepAliveInterval The interval for sending keep-alive messages to clients.
-	 * @throws IllegalArgumentException if any parameter is null
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
-			String sseEndpoint, Duration keepAliveInterval) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
-				(serverRequest) -> McpTransportContext.EMPTY);
-	}
-
 	/**
 	 * Constructs a new WebMvcSseServerTransportProvider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * @param jsonMapper The McpJsonMapper to use for JSON serialization/deserialization
 	 * of messages.
 	 * @param baseUrl The base URL for the message endpoint, used to construct the full
 	 * endpoint URL for clients.
@@ -209,16 +133,16 @@ public WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUr
 	 * {@link McpTransportContext}.
 	 * @throws IllegalArgumentException if any parameter is null
 	 */
-	private WebMvcSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+	private WebMvcSseServerTransportProvider(McpJsonMapper jsonMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval,
 			McpTransportContextExtractor contextExtractor) {
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(jsonMapper, "McpJsonMapper must not be null");
 		Assert.notNull(baseUrl, "Message base URL must not be null");
 		Assert.notNull(messageEndpoint, "Message endpoint must not be null");
 		Assert.notNull(sseEndpoint, "SSE endpoint must not be null");
 		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.baseUrl = baseUrl;
 		this.messageEndpoint = messageEndpoint;
 		this.sseEndpoint = sseEndpoint;
@@ -399,7 +323,7 @@ private ServerResponse handleMessage(ServerRequest request) {
 			final McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 			String body = request.body(String.class);
-			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 
 			// Process the message through the session's handle method
 			session.handle(message).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)).block(); // Block
@@ -456,7 +380,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			return Mono.fromRunnable(() -> {
 				sseBuilderLock.lock();
 				try {
-					String jsonText = objectMapper.writeValueAsString(message);
+					String jsonText = jsonMapper.writeValueAsString(message);
 					sseBuilder.id(sessionId).event(MESSAGE_EVENT_TYPE).data(jsonText);
 					logger.debug("Message sent to session {}", sessionId);
 				}
@@ -471,15 +395,15 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 		}
 
 		/**
-		 * Converts data from one type to another using the configured ObjectMapper.
+		 * Converts data from one type to another using the configured McpJsonMapper.
 		 * @param data The source data object to convert
 		 * @param typeRef The target type reference
 		 * @return The converted object of type T
 		 * @param  The target type
 		 */
 		@Override
-		public  T unmarshalFrom(Object data, TypeReference typeRef) {
-			return objectMapper.convertValue(data, typeRef);
+		public  T unmarshalFrom(Object data, TypeRef typeRef) {
+			return jsonMapper.convertValue(data, typeRef);
 		}
 
 		/**
@@ -541,7 +465,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper = new ObjectMapper();
+		private McpJsonMapper jsonMapper;
 
 		private String baseUrl = "";
 
@@ -556,12 +480,12 @@ public static class Builder {
 
 		/**
 		 * Sets the JSON object mapper to use for message serialization/deserialization.
-		 * @param objectMapper The object mapper to use
+		 * @param jsonMapper The object mapper to use
 		 * @return This builder instance for method chaining
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "McpJsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -633,14 +557,14 @@ public Builder contextExtractor(McpTransportContextExtractor cont
 		 * Builds a new instance of WebMvcSseServerTransportProvider with the configured
 		 * settings.
 		 * @return A new WebMvcSseServerTransportProvider instance
-		 * @throws IllegalStateException if objectMapper or messageEndpoint is not set
+		 * @throws IllegalStateException if jsonMapper or messageEndpoint is not set
 		 */
 		public WebMvcSseServerTransportProvider build() {
 			if (messageEndpoint == null) {
 				throw new IllegalStateException("MessageEndpoint must be set");
 			}
-			return new WebMvcSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
-					keepAliveInterval, contextExtractor);
+			return new WebMvcSseServerTransportProvider(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval, contextExtractor);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
index fc2da0439..4223084ff 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStatelessServerTransport.java
@@ -4,8 +4,8 @@
 
 package io.modelcontextprotocol.server.transport;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
@@ -38,7 +38,7 @@ public class WebMvcStatelessServerTransport implements McpStatelessServerTranspo
 
 	private static final Logger logger = LoggerFactory.getLogger(WebMvcStatelessServerTransport.class);
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final String mcpEndpoint;
 
@@ -50,13 +50,13 @@ public class WebMvcStatelessServerTransport implements McpStatelessServerTranspo
 
 	private volatile boolean isClosing = false;
 
-	private WebMvcStatelessServerTransport(ObjectMapper objectMapper, String mcpEndpoint,
+	private WebMvcStatelessServerTransport(McpJsonMapper jsonMapper, String mcpEndpoint,
 			McpTransportContextExtractor contextExtractor) {
-		Assert.notNull(objectMapper, "objectMapper must not be null");
+		Assert.notNull(jsonMapper, "jsonMapper must not be null");
 		Assert.notNull(mcpEndpoint, "mcpEndpoint must not be null");
 		Assert.notNull(contextExtractor, "contextExtractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.mcpEndpoint = mcpEndpoint;
 		this.contextExtractor = contextExtractor;
 		this.routerFunction = RouterFunctions.route()
@@ -110,7 +110,7 @@ private ServerResponse handlePost(ServerRequest request) {
 
 		try {
 			String body = request.body(String.class);
-			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 
 			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
 				try {
@@ -171,7 +171,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private String mcpEndpoint = "/mcp";
 
@@ -185,13 +185,13 @@ private Builder() {
 		/**
 		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
-		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @param jsonMapper The ObjectMapper instance. Must not be null.
 		 * @return this builder instance
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "ObjectMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -230,10 +230,9 @@ public Builder contextExtractor(McpTransportContextExtractor cont
 		 * @throws IllegalStateException if required parameters are not set
 		 */
 		public WebMvcStatelessServerTransport build() {
-			Assert.notNull(objectMapper, "ObjectMapper must be set");
 			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
-
-			return new WebMvcStatelessServerTransport(objectMapper, mcpEndpoint, contextExtractor);
+			return new WebMvcStatelessServerTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					mcpEndpoint, contextExtractor);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index 3cc104dd4..9bb9bfa86 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -10,6 +10,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
 
+import io.modelcontextprotocol.json.McpJsonMapper;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpStatus;
@@ -20,8 +21,7 @@
 import org.springframework.web.servlet.function.ServerResponse;
 import org.springframework.web.servlet.function.ServerResponse.SseBuilder;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
@@ -82,7 +82,7 @@ public class WebMvcStreamableServerTransportProvider implements McpStreamableSer
 	 */
 	private final boolean disallowDelete;
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final RouterFunction routerFunction;
 
@@ -104,7 +104,7 @@ public class WebMvcStreamableServerTransportProvider implements McpStreamableSer
 
 	/**
 	 * Constructs a new WebMvcStreamableServerTransportProvider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * @param jsonMapper The McpJsonMapper to use for JSON serialization/deserialization
 	 * of messages.
 	 * @param baseUrl The base URL for the message endpoint, used to construct the full
 	 * endpoint URL for clients.
@@ -113,14 +113,14 @@ public class WebMvcStreamableServerTransportProvider implements McpStreamableSer
 	 * @param disallowDelete Whether to disallow DELETE requests on the endpoint.
 	 * @throws IllegalArgumentException if any parameter is null
 	 */
-	private WebMvcStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
+	private WebMvcStreamableServerTransportProvider(McpJsonMapper jsonMapper, String mcpEndpoint,
 			boolean disallowDelete, McpTransportContextExtractor contextExtractor,
 			Duration keepAliveInterval) {
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(jsonMapper, "McpJsonMapper must not be null");
 		Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
 		Assert.notNull(contextExtractor, "McpTransportContextExtractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.mcpEndpoint = mcpEndpoint;
 		this.disallowDelete = disallowDelete;
 		this.contextExtractor = contextExtractor;
@@ -325,13 +325,13 @@ private ServerResponse handlePost(ServerRequest request) {
 
 		try {
 			String body = request.body(String.class);
-			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body);
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body);
 
 			// Handle initialization request
 			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest
 					&& jsonrpcRequest.method().equals(McpSchema.METHOD_INITIALIZE)) {
-				McpSchema.InitializeRequest initializeRequest = objectMapper.convertValue(jsonrpcRequest.params(),
-						new TypeReference() {
+				McpSchema.InitializeRequest initializeRequest = jsonMapper.convertValue(jsonrpcRequest.params(),
+						new TypeRef() {
 						});
 				McpStreamableServerSession.McpStreamableServerSessionInit init = this.sessionFactory
 					.startSession(initializeRequest);
@@ -516,7 +516,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId
 						return;
 					}
 
-					String jsonText = objectMapper.writeValueAsString(message);
+					String jsonText = jsonMapper.writeValueAsString(message);
 					this.sseBuilder.id(messageId != null ? messageId : this.sessionId)
 						.event(MESSAGE_EVENT_TYPE)
 						.data(jsonText);
@@ -539,15 +539,15 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId
 		}
 
 		/**
-		 * Converts data from one type to another using the configured ObjectMapper.
+		 * Converts data from one type to another using the configured McpJsonMapper.
 		 * @param data The source data object to convert
 		 * @param typeRef The target type reference
 		 * @return The converted object of type T
 		 * @param  The target type
 		 */
 		@Override
-		public  T unmarshalFrom(Object data, TypeReference typeRef) {
-			return objectMapper.convertValue(data, typeRef);
+		public  T unmarshalFrom(Object data, TypeRef typeRef) {
+			return jsonMapper.convertValue(data, typeRef);
 		}
 
 		/**
@@ -597,7 +597,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private String mcpEndpoint = "/mcp";
 
@@ -609,15 +609,15 @@ public static class Builder {
 		private Duration keepAliveInterval;
 
 		/**
-		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * Sets the McpJsonMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
-		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @param jsonMapper The McpJsonMapper instance. Must not be null.
 		 * @return this builder instance
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "McpJsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -678,11 +678,10 @@ public Builder keepAliveInterval(Duration keepAliveInterval) {
 		 * @throws IllegalStateException if required parameters are not set
 		 */
 		public WebMvcStreamableServerTransportProvider build() {
-			Assert.notNull(this.objectMapper, "ObjectMapper must be set");
 			Assert.notNull(this.mcpEndpoint, "MCP endpoint must be set");
-
-			return new WebMvcStreamableServerTransportProvider(this.objectMapper, this.mcpEndpoint, this.disallowDelete,
-					this.contextExtractor, this.keepAliveInterval);
+			return new WebMvcStreamableServerTransportProvider(
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, mcpEndpoint, disallowDelete,
+					contextExtractor, keepAliveInterval);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
index 1f5f1cc0c..cc9945436 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java
@@ -8,7 +8,6 @@
 import java.util.function.BiFunction;
 import java.util.function.Supplier;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.McpSyncClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
@@ -40,7 +39,6 @@
 import org.springframework.web.servlet.function.RouterFunction;
 import org.springframework.web.servlet.function.ServerRequest;
 import org.springframework.web.servlet.function.ServerResponse;
-
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
@@ -223,10 +221,7 @@ static class TestStatelessConfig {
 		@Bean
 		public WebMvcStatelessServerTransport webMvcStatelessServerTransport() {
 
-			return WebMvcStatelessServerTransport.builder()
-				.objectMapper(new ObjectMapper())
-				.contextExtractor(serverContextExtractor)
-				.build();
+			return WebMvcStatelessServerTransport.builder().contextExtractor(serverContextExtractor).build();
 		}
 
 		@Bean
@@ -251,10 +246,7 @@ static class TestStreamableHttpConfig {
 		@Bean
 		public WebMvcStreamableServerTransportProvider webMvcStreamableServerTransport() {
 
-			return WebMvcStreamableServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
-				.contextExtractor(serverContextExtractor)
-				.build();
+			return WebMvcStreamableServerTransportProvider.builder().contextExtractor(serverContextExtractor).build();
 		}
 
 		@Bean
@@ -281,7 +273,6 @@ static class TestSseConfig {
 		public WebMvcSseServerTransportProvider webMvcSseServerTransport() {
 
 			return WebMvcSseServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
 				.contextExtractor(serverContextExtractor)
 				.messageEndpoint("/mcp/message")
 				.build();
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
index 66349216d..ae1f4f4d1 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
@@ -16,8 +16,6 @@
 import org.springframework.web.servlet.function.RouterFunction;
 import org.springframework.web.servlet.function.ServerResponse;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import reactor.netty.DisposableServer;
@@ -48,10 +46,7 @@ static class TestConfig {
 
 		@Bean
 		public WebMvcStreamableServerTransportProvider webMvcSseServerTransportProvider() {
-			return WebMvcStreamableServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
-				.mcpEndpoint(MCP_ENDPOINT)
-				.build();
+			return WebMvcStreamableServerTransportProvider.builder().mcpEndpoint(MCP_ENDPOINT).build();
 		}
 
 		@Bean
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
index cab487f12..c8c24b8a7 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
@@ -16,8 +16,6 @@
 import org.springframework.web.servlet.function.RouterFunction;
 import org.springframework.web.servlet.function.ServerResponse;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import reactor.netty.DisposableServer;
@@ -48,10 +46,7 @@ static class TestConfig {
 
 		@Bean
 		public WebMvcStreamableServerTransportProvider webMvcSseServerTransportProvider() {
-			return WebMvcStreamableServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
-				.mcpEndpoint(MCP_ENDPOINT)
-				.build();
+			return WebMvcStreamableServerTransportProvider.builder().mcpEndpoint(MCP_ENDPOINT).build();
 		}
 
 		@Bean
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java
index bb4c2bf37..ccf3170c9 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseAsyncServerTransportTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import org.apache.catalina.Context;
@@ -37,7 +36,10 @@ static class TestConfig {
 
 		@Bean
 		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
-			return new WebMvcSseServerTransportProvider(new ObjectMapper(), MESSAGE_ENDPOINT);
+			return WebMvcSseServerTransportProvider.builder()
+				.messageEndpoint(MESSAGE_ENDPOINT)
+				.sseEndpoint(WebMvcSseServerTransportProvider.DEFAULT_SSE_ENDPOINT)
+				.build();
 		}
 
 		@Bean
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java
index cce36d191..d8d26af48 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseCustomContextPathTests.java
@@ -3,7 +3,6 @@
  */
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
@@ -92,7 +91,6 @@ static class TestConfig {
 		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
 
 			return WebMvcSseServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
 				.baseUrl(CUSTOM_CONTEXT_PATH)
 				.messageEndpoint(MESSAGE_ENDPOINT)
 				.sseEndpoint(WebMvcSseServerTransportProvider.DEFAULT_SSE_ENDPOINT)
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index 18a9d0063..e780b8e51 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -21,8 +21,6 @@
 import org.springframework.web.servlet.function.ServerRequest;
 import org.springframework.web.servlet.function.ServerResponse;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.AbstractMcpClientServerIntegrationTests;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
@@ -64,7 +62,6 @@ static class TestConfig {
 		@Bean
 		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
 			return WebMvcSseServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
 				.messageEndpoint(MESSAGE_ENDPOINT)
 				.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 				.build();
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
index 101a067ad..66d6d3ae9 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseSyncServerTransportTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
 import org.apache.catalina.Context;
 import org.apache.catalina.LifecycleException;
@@ -36,10 +35,7 @@ static class TestConfig {
 
 		@Bean
 		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
-			return WebMvcSseServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
-				.messageEndpoint(MESSAGE_ENDPOINT)
-				.build();
+			return WebMvcSseServerTransportProvider.builder().messageEndpoint(MESSAGE_ENDPOINT).build();
 		}
 
 		@Bean
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
index c7c1e710d..9633dfbd1 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
@@ -19,8 +19,6 @@
 import org.springframework.web.servlet.function.RouterFunction;
 import org.springframework.web.servlet.function.ServerResponse;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.AbstractStatelessIntegrationTests;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
@@ -46,10 +44,7 @@ static class TestConfig {
 		@Bean
 		public WebMvcStatelessServerTransport webMvcStatelessServerTransport() {
 
-			return WebMvcStatelessServerTransport.builder()
-				.objectMapper(new ObjectMapper())
-				.messageEndpoint(MESSAGE_ENDPOINT)
-				.build();
+			return WebMvcStatelessServerTransport.builder().messageEndpoint(MESSAGE_ENDPOINT).build();
 
 		}
 
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
index 3f1716f89..abdd82967 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -21,8 +21,6 @@
 import org.springframework.web.servlet.function.RouterFunction;
 import org.springframework.web.servlet.function.ServerResponse;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.AbstractMcpClientServerIntegrationTests;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
@@ -52,7 +50,6 @@ static class TestConfig {
 		@Bean
 		public WebMvcStreamableServerTransportProvider webMvcStreamableServerTransportProvider() {
 			return WebMvcStreamableServerTransportProvider.builder()
-				.objectMapper(new ObjectMapper())
 				.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 				.mcpEndpoint(MESSAGE_ENDPOINT)
 				.build();
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 113c8d1c2..a36d9006a 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -54,6 +54,7 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -81,7 +82,6 @@ void simple(String clientType) {
 		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.requestTimeout(Duration.ofSeconds(1000))
 			.build();
-
 		try (
 				// Create client without sampling capabilities
 				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
@@ -106,7 +106,7 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 				return exchange.createMessage(mock(McpSchema.CreateMessageRequest.class))
 					.then(Mono.just(mock(CallToolResult.class)));
@@ -155,7 +155,7 @@ void testCreateMessageSuccess(String clientType) {
 		AtomicReference samplingResult = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
@@ -233,7 +233,7 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 		AtomicReference samplingResult = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
@@ -307,7 +307,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 				null);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
@@ -357,7 +357,7 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> exchange.createElicitation(mock(ElicitRequest.class))
 				.then(Mono.just(mock(CallToolResult.class))))
 			.build();
@@ -400,7 +400,7 @@ void testCreateElicitationSuccess(String clientType) {
 				null);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var elicitationRequest = McpSchema.ElicitRequest.builder()
@@ -457,7 +457,7 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 		AtomicReference resultRef = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var elicitationRequest = McpSchema.ElicitRequest.builder()
@@ -528,7 +528,7 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 		AtomicReference resultRef = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var elicitationRequest = ElicitRequest.builder()
@@ -626,7 +626,7 @@ void testRootsWithoutCapability(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				exchange.listRoots(); // try to list roots
@@ -757,14 +757,6 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testToolCallSuccess(String clientType) {
@@ -774,7 +766,7 @@ void testToolCallSuccess(String clientType) {
 		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				try {
@@ -828,7 +820,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 				.tool(Tool.builder()
 					.name("tool1")
 					.description("tool1 description")
-					.inputSchema(emptyJsonSchema)
+					.inputSchema(EMPTY_JSON_SCHEMA)
 					.build())
 				.callHandler((exchange, request) -> {
 					// We trigger a timeout on blocking read, raising an exception
@@ -867,7 +859,7 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 		var expectedCallResponse = new McpSchema.CallToolResult(
 				List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=value")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				McpTransportContext transportContext = exchange.transportContext();
@@ -919,7 +911,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 				// perform a blocking call to a remote service
 				try {
@@ -988,7 +980,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 				.tool(Tool.builder()
 					.name("tool2")
 					.description("tool2 description")
-					.inputSchema(emptyJsonSchema)
+					.inputSchema(EMPTY_JSON_SCHEMA)
 					.build())
 				.callHandler((exchange, request) -> callResponse)
 				.build();
@@ -1040,7 +1032,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 			.tool(Tool.builder()
 				.name("logging-test")
 				.description("Test logging notifications")
-				.inputSchema(emptyJsonSchema)
+				.inputSchema(EMPTY_JSON_SCHEMA)
 				.build())
 			.callHandler((exchange, request) -> {
 
@@ -1154,7 +1146,7 @@ void testProgressNotification(String clientType) throws InterruptedException {
 			.tool(McpSchema.Tool.builder()
 				.name("progress-test")
 				.description("Test progress notifications")
-				.inputSchema(emptyJsonSchema)
+				.inputSchema(EMPTY_JSON_SCHEMA)
 				.build())
 			.callHandler((exchange, request) -> {
 
@@ -1308,7 +1300,7 @@ void testPingSuccess(String clientType) {
 			.tool(Tool.builder()
 				.name("ping-async-test")
 				.description("Test ping async behavior")
-				.inputSchema(emptyJsonSchema)
+				.inputSchema(EMPTY_JSON_SCHEMA)
 				.build())
 			.callHandler((exchange, request) -> {
 
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
index d4a84c7c8..705535e93 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
@@ -31,6 +31,7 @@
 import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 
+import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -74,15 +75,6 @@ void simple(String clientType) {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient", "webflux" })
 	void testToolCallSuccess(String clientType) {
@@ -92,7 +84,7 @@ void testToolCallSuccess(String clientType) {
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpStatelessServerFeatures.SyncToolSpecification tool1 = McpStatelessServerFeatures.SyncToolSpecification
 			.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((ctx, request) -> {
 
 				try {
@@ -145,7 +137,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 				.tool(Tool.builder()
 					.name("tool1")
 					.description("tool1 description")
-					.inputSchema(emptyJsonSchema)
+					.inputSchema(EMPTY_JSON_SCHEMA)
 					.build())
 				.callHandler((context, request) -> {
 					// We trigger a timeout on blocking read, raising an exception
@@ -180,7 +172,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpStatelessServerFeatures.SyncToolSpecification tool1 = McpStatelessServerFeatures.SyncToolSpecification
 			.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((ctx, request) -> {
 				// perform a blocking call to a remote service
 				try {
@@ -241,7 +233,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 				.tool(Tool.builder()
 					.name("tool2")
 					.description("tool2 description")
-					.inputSchema(emptyJsonSchema)
+					.inputSchema(EMPTY_JSON_SCHEMA)
 					.build())
 				.callHandler((exchange, request) -> callResponse)
 				.build();
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/MockMcpTransport.java b/mcp-test/src/main/java/io/modelcontextprotocol/MockMcpTransport.java
index 5484a63c2..cd8458311 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/MockMcpTransport.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/MockMcpTransport.java
@@ -9,8 +9,8 @@
 import java.util.function.BiConsumer;
 import java.util.function.Function;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCNotification;
@@ -93,8 +93,8 @@ public Mono closeGracefully() {
 	}
 
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return new ObjectMapper().convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return McpJsonMapper.getDefault().convertValue(data, typeRef);
 	}
 
 }
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 8902a53b3..8a0b3e0d9 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.client;
 
+import static io.modelcontextprotocol.utils.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -22,8 +23,7 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
+import io.modelcontextprotocol.json.McpJsonMapper;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
@@ -176,7 +176,12 @@ void testListAllToolsReturnsImmutableList() {
 				.consumeNextWith(result -> {
 					assertThat(result.tools()).isNotNull();
 					// Verify that the returned list is immutable
-					assertThatThrownBy(() -> result.tools().add(new Tool("test", "test", "{\"type\":\"object\"}")))
+					assertThatThrownBy(() -> result.tools()
+						.add(Tool.builder()
+							.name("test")
+							.title("test")
+							.inputSchema(JSON_MAPPER, "{\"type\":\"object\"}")
+							.build()))
 						.isInstanceOf(UnsupportedOperationException.class);
 				})
 				.verifyComplete();
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 8eb6ec248..e1ffd2c75 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -22,8 +22,6 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index 1e87d4420..b0701911a 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -26,6 +26,7 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -95,18 +96,10 @@ void testImmediateClose() {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
 	@Test
 	@Deprecated
 	void testAddTool() {
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
@@ -120,7 +113,7 @@ void testAddTool() {
 
 	@Test
 	void testAddToolCall() {
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
@@ -136,7 +129,11 @@ void testAddToolCall() {
 	@Test
 	@Deprecated
 	void testAddDuplicateTool() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -156,7 +153,11 @@ void testAddDuplicateTool() {
 
 	@Test
 	void testAddDuplicateToolCall() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -176,8 +177,11 @@ void testAddDuplicateToolCall() {
 
 	@Test
 	void testDuplicateToolCallDuringBuilding() {
-		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
-				emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("duplicate-build-toolcall")
+			.title("Duplicate toolcall during building")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -189,7 +193,11 @@ void testDuplicateToolCallDuringBuilding() {
 
 	@Test
 	void testDuplicateToolsInBatchListRegistration() {
-		Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("batch-list-tool")
+			.title("Duplicate tool in batch list")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		List specs = List.of(
 				McpServerFeatures.AsyncToolSpecification.builder()
 					.tool(duplicateTool)
@@ -210,7 +218,11 @@ void testDuplicateToolsInBatchListRegistration() {
 
 	@Test
 	void testDuplicateToolsInBatchVarargsRegistration() {
-		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("batch-varargs-tool")
+			.title("Duplicate tool in batch varargs")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -229,8 +241,11 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 
 	@Test
 	void testRemoveTool() {
-		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
-
+		Tool too = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
@@ -256,7 +271,11 @@ void testRemoveNonexistentTool() {
 
 	@Test
 	void testNotifyToolsListChanged() {
-		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool too = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 5d70ae4c0..d804de43b 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -99,15 +100,6 @@ void testGetAsyncServer() {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
 	@Test
 	@Deprecated
 	void testAddTool() {
@@ -115,7 +107,7 @@ void testAddTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(newTool,
 				(exchange, args) -> new CallToolResult(List.of(), false))))
 			.doesNotThrowAnyException();
@@ -129,7 +121,7 @@ void testAddToolCall() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(newTool)
 			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
@@ -141,7 +133,11 @@ void testAddToolCall() {
 	@Test
 	@Deprecated
 	void testAddDuplicateTool() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -158,7 +154,11 @@ void testAddDuplicateTool() {
 
 	@Test
 	void testAddDuplicateToolCall() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -176,8 +176,11 @@ void testAddDuplicateToolCall() {
 
 	@Test
 	void testDuplicateToolCallDuringBuilding() {
-		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
-				emptyJsonSchema);
+		Tool duplicateTool = Tool.builder()
+			.name("duplicate-build-toolcall")
+			.title("Duplicate toolcall during building")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -189,7 +192,11 @@ void testDuplicateToolCallDuringBuilding() {
 
 	@Test
 	void testDuplicateToolsInBatchListRegistration() {
-		Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema);
+		Tool duplicateTool = Tool.builder()
+			.name("batch-list-tool")
+			.title("Duplicate tool in batch list")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		List specs = List.of(
 				McpServerFeatures.SyncToolSpecification.builder()
 					.tool(duplicateTool)
@@ -210,7 +217,11 @@ void testDuplicateToolsInBatchListRegistration() {
 
 	@Test
 	void testDuplicateToolsInBatchVarargsRegistration() {
-		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
+		Tool duplicateTool = Tool.builder()
+			.name("batch-varargs-tool")
+			.title("Duplicate tool in batch varargs")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -229,7 +240,7 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 
 	@Test
 	void testRemoveTool() {
-		Tool tool = new McpSchema.Tool(TEST_TOOL_NAME, "Test tool", emptyJsonSchema);
+		Tool tool = Tool.builder().name(TEST_TOOL_NAME).title("Test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java b/mcp-test/src/main/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
new file mode 100644
index 000000000..e9ec8900c
--- /dev/null
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
@@ -0,0 +1,12 @@
+package io.modelcontextprotocol.utils;
+
+import io.modelcontextprotocol.json.McpJsonMapper;
+
+public final class McpJsonMapperUtils {
+
+	private McpJsonMapperUtils() {
+	}
+
+	public static final McpJsonMapper JSON_MAPPER = McpJsonMapper.getDefault();
+
+}
\ No newline at end of file
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/utils/ToolsUtils.java b/mcp-test/src/main/java/io/modelcontextprotocol/utils/ToolsUtils.java
new file mode 100644
index 000000000..ec603aac1
--- /dev/null
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/utils/ToolsUtils.java
@@ -0,0 +1,15 @@
+package io.modelcontextprotocol.utils;
+
+import io.modelcontextprotocol.spec.McpSchema;
+
+import java.util.Collections;
+
+public final class ToolsUtils {
+
+	private ToolsUtils() {
+	}
+
+	public static final McpSchema.JsonSchema EMPTY_JSON_SCHEMA = new McpSchema.JsonSchema("object",
+			Collections.emptyMap(), null, null, null, null);
+
+}
diff --git a/mcp/pom.xml b/mcp/pom.xml
index dc85a419e..6ba402a4d 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -65,6 +65,11 @@
 	
 
 	
+        
+            io.modelcontextprotocol.sdk
+            mcp-json-jackson2
+            0.13.0-SNAPSHOT
+        
 
 		
 			org.slf4j
@@ -74,7 +79,7 @@
 
 		
 			com.fasterxml.jackson.core
-			jackson-databind
+			jackson-annotations
 			${jackson.version}
 		
 
@@ -83,11 +88,6 @@
 			reactor-core
 		
 
-		
-			com.networknt
-			json-schema-validator
-			${json-schema-validator.version}
-		
 
 		
 		
@@ -216,8 +216,14 @@
 			test
 		
 
-
+        
+        
+            com.google.code.gson
+            gson
+            2.10.1
+            test
+        
 	
 
 
-
\ No newline at end of file
+
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index eb6d42f68..8d5bc34a6 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -18,11 +18,10 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpClientTransport;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
@@ -85,25 +84,25 @@ public class McpAsyncClient {
 
 	private static final Logger logger = LoggerFactory.getLogger(McpAsyncClient.class);
 
-	private static final TypeReference VOID_TYPE_REFERENCE = new TypeReference<>() {
+	private static final TypeRef VOID_TYPE_REFERENCE = new TypeRef<>() {
 	};
 
-	public static final TypeReference OBJECT_TYPE_REF = new TypeReference<>() {
+	public static final TypeRef OBJECT_TYPE_REF = new TypeRef<>() {
 	};
 
-	public static final TypeReference PAGINATED_REQUEST_TYPE_REF = new TypeReference<>() {
+	public static final TypeRef PAGINATED_REQUEST_TYPE_REF = new TypeRef<>() {
 	};
 
-	public static final TypeReference INITIALIZE_RESULT_TYPE_REF = new TypeReference<>() {
+	public static final TypeRef INITIALIZE_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	public static final TypeReference CREATE_MESSAGE_REQUEST_TYPE_REF = new TypeReference<>() {
+	public static final TypeRef CREATE_MESSAGE_REQUEST_TYPE_REF = new TypeRef<>() {
 	};
 
-	public static final TypeReference LOGGING_MESSAGE_NOTIFICATION_TYPE_REF = new TypeReference<>() {
+	public static final TypeRef LOGGING_MESSAGE_NOTIFICATION_TYPE_REF = new TypeRef<>() {
 	};
 
-	public static final TypeReference PROGRESS_NOTIFICATION_TYPE_REF = new TypeReference<>() {
+	public static final TypeRef PROGRESS_NOTIFICATION_TYPE_REF = new TypeRef<>() {
 	};
 
 	/**
@@ -512,7 +511,7 @@ private RequestHandler samplingCreateMessageHandler() {
 	// --------------------------
 	private RequestHandler elicitationCreateHandler() {
 		return params -> {
-			ElicitRequest request = transport.unmarshalFrom(params, new TypeReference<>() {
+			ElicitRequest request = transport.unmarshalFrom(params, new TypeRef<>() {
 			});
 
 			return this.elicitationHandler.apply(request);
@@ -522,10 +521,10 @@ private RequestHandler elicitationCreateHandler() {
 	// --------------------------
 	// Tools
 	// --------------------------
-	private static final TypeReference CALL_TOOL_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef CALL_TOOL_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	private static final TypeReference LIST_TOOLS_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef LIST_TOOLS_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
 	/**
@@ -596,13 +595,13 @@ private NotificationHandler asyncToolsChangeNotificationHandler(
 	// Resources
 	// --------------------------
 
-	private static final TypeReference LIST_RESOURCES_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef LIST_RESOURCES_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	private static final TypeReference READ_RESOURCE_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef READ_RESOURCE_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	private static final TypeReference LIST_RESOURCE_TEMPLATES_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef LIST_RESOURCE_TEMPLATES_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
 	/**
@@ -756,7 +755,7 @@ private NotificationHandler asyncResourcesUpdatedNotificationHandler(
 			List, Mono>> resourcesUpdateConsumers) {
 		return params -> {
 			McpSchema.ResourcesUpdatedNotification resourcesUpdatedNotification = transport.unmarshalFrom(params,
-					new TypeReference<>() {
+					new TypeRef<>() {
 					});
 
 			return readResource(new McpSchema.ReadResourceRequest(resourcesUpdatedNotification.uri()))
@@ -773,10 +772,10 @@ private NotificationHandler asyncResourcesUpdatedNotificationHandler(
 	// --------------------------
 	// Prompts
 	// --------------------------
-	private static final TypeReference LIST_PROMPTS_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef LIST_PROMPTS_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	private static final TypeReference GET_PROMPT_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef GET_PROMPT_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
 	/**
@@ -911,7 +910,7 @@ void setProtocolVersions(List protocolVersions) {
 	// --------------------------
 	// Completions
 	// --------------------------
-	private static final TypeReference COMPLETION_COMPLETE_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef COMPLETION_COMPLETE_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
index c2c74dcae..661a41170 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
@@ -19,8 +19,8 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
@@ -97,8 +97,8 @@ public class HttpClientSseClientTransport implements McpClientTransport {
 	/** HTTP request builder for building requests to send messages to the server */
 	private final HttpRequest.Builder requestBuilder;
 
-	/** JSON object mapper for message serialization/deserialization */
-	protected ObjectMapper objectMapper;
+	/** JSON mapper for message serialization/deserialization */
+	protected McpJsonMapper jsonMapper;
 
 	/** Flag indicating if the transport is in closing state */
 	private volatile boolean isClosing = false;
@@ -117,81 +117,6 @@ public class HttpClientSseClientTransport implements McpClientTransport {
 	 */
 	private final McpAsyncHttpClientRequestCustomizer httpRequestCustomizer;
 
-	/**
-	 * Creates a new transport instance with default HTTP client and object mapper.
-	 * @param baseUri the base URI of the MCP server
-	 * @deprecated Use {@link HttpClientSseClientTransport#builder(String)} instead. This
-	 * constructor will be removed in future versions.
-	 */
-	@Deprecated(forRemoval = true)
-	public HttpClientSseClientTransport(String baseUri) {
-		this(HttpClient.newBuilder(), baseUri, new ObjectMapper());
-	}
-
-	/**
-	 * Creates a new transport instance with custom HTTP client builder and object mapper.
-	 * @param clientBuilder the HTTP client builder to use
-	 * @param baseUri the base URI of the MCP server
-	 * @param objectMapper the object mapper for JSON serialization/deserialization
-	 * @throws IllegalArgumentException if objectMapper or clientBuilder is null
-	 * @deprecated Use {@link HttpClientSseClientTransport#builder(String)} instead. This
-	 * constructor will be removed in future versions.
-	 */
-	@Deprecated(forRemoval = true)
-	public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, String baseUri, ObjectMapper objectMapper) {
-		this(clientBuilder, baseUri, DEFAULT_SSE_ENDPOINT, objectMapper);
-	}
-
-	/**
-	 * Creates a new transport instance with custom HTTP client builder and object mapper.
-	 * @param clientBuilder the HTTP client builder to use
-	 * @param baseUri the base URI of the MCP server
-	 * @param sseEndpoint the SSE endpoint path
-	 * @param objectMapper the object mapper for JSON serialization/deserialization
-	 * @throws IllegalArgumentException if objectMapper or clientBuilder is null
-	 * @deprecated Use {@link HttpClientSseClientTransport#builder(String)} instead. This
-	 * constructor will be removed in future versions.
-	 */
-	@Deprecated(forRemoval = true)
-	public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, String baseUri, String sseEndpoint,
-			ObjectMapper objectMapper) {
-		this(clientBuilder, HttpRequest.newBuilder(), baseUri, sseEndpoint, objectMapper);
-	}
-
-	/**
-	 * Creates a new transport instance with custom HTTP client builder, object mapper,
-	 * and headers.
-	 * @param clientBuilder the HTTP client builder to use
-	 * @param requestBuilder the HTTP request builder to use
-	 * @param baseUri the base URI of the MCP server
-	 * @param sseEndpoint the SSE endpoint path
-	 * @param objectMapper the object mapper for JSON serialization/deserialization
-	 * @throws IllegalArgumentException if objectMapper, clientBuilder, or headers is null
-	 * @deprecated Use {@link HttpClientSseClientTransport#builder(String)} instead. This
-	 * constructor will be removed in future versions.
-	 */
-	@Deprecated(forRemoval = true)
-	public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpRequest.Builder requestBuilder,
-			String baseUri, String sseEndpoint, ObjectMapper objectMapper) {
-		this(clientBuilder.build(), requestBuilder, baseUri, sseEndpoint, objectMapper);
-	}
-
-	/**
-	 * Creates a new transport instance with custom HTTP client builder, object mapper,
-	 * and headers.
-	 * @param httpClient the HTTP client to use
-	 * @param requestBuilder the HTTP request builder to use
-	 * @param baseUri the base URI of the MCP server
-	 * @param sseEndpoint the SSE endpoint path
-	 * @param objectMapper the object mapper for JSON serialization/deserialization
-	 * @throws IllegalArgumentException if objectMapper, clientBuilder, or headers is null
-	 */
-	@Deprecated(forRemoval = true)
-	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
-			String sseEndpoint, ObjectMapper objectMapper) {
-		this(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper, McpAsyncHttpClientRequestCustomizer.NOOP);
-	}
-
 	/**
 	 * Creates a new transport instance with custom HTTP client builder, object mapper,
 	 * and headers.
@@ -199,14 +124,14 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 	 * @param requestBuilder the HTTP request builder to use
 	 * @param baseUri the base URI of the MCP server
 	 * @param sseEndpoint the SSE endpoint path
-	 * @param objectMapper the object mapper for JSON serialization/deserialization
+	 * @param jsonMapper the object mapper for JSON serialization/deserialization
 	 * @param httpRequestCustomizer customizer for the requestBuilder before executing
 	 * requests
 	 * @throws IllegalArgumentException if objectMapper, clientBuilder, or headers is null
 	 */
 	HttpClientSseClientTransport(HttpClient httpClient, HttpRequest.Builder requestBuilder, String baseUri,
-			String sseEndpoint, ObjectMapper objectMapper, McpAsyncHttpClientRequestCustomizer httpRequestCustomizer) {
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+			String sseEndpoint, McpJsonMapper jsonMapper, McpAsyncHttpClientRequestCustomizer httpRequestCustomizer) {
+		Assert.notNull(jsonMapper, "jsonMapper must not be null");
 		Assert.hasText(baseUri, "baseUri must not be empty");
 		Assert.hasText(sseEndpoint, "sseEndpoint must not be empty");
 		Assert.notNull(httpClient, "httpClient must not be null");
@@ -214,7 +139,7 @@ public HttpClientSseClientTransport(HttpClient.Builder clientBuilder, HttpReques
 		Assert.notNull(httpRequestCustomizer, "httpRequestCustomizer must not be null");
 		this.baseUri = URI.create(baseUri);
 		this.sseEndpoint = sseEndpoint;
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.httpClient = httpClient;
 		this.requestBuilder = requestBuilder;
 		this.httpRequestCustomizer = httpRequestCustomizer;
@@ -245,7 +170,7 @@ public static class Builder {
 
 		private HttpClient.Builder clientBuilder = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1);
 
-		private ObjectMapper objectMapper = new ObjectMapper();
+		private McpJsonMapper jsonMapper;
 
 		private HttpRequest.Builder requestBuilder = HttpRequest.newBuilder();
 
@@ -340,13 +265,13 @@ public Builder customizeRequest(final Consumer requestCusto
 		}
 
 		/**
-		 * Sets the object mapper for JSON serialization/deserialization.
-		 * @param objectMapper the object mapper
+		 * Sets the JSON mapper implementation to use for serialization/deserialization.
+		 * @param jsonMapper the JSON mapper
 		 * @return this builder
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "objectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "jsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -402,8 +327,8 @@ public Builder connectTimeout(Duration connectTimeout) {
 		 */
 		public HttpClientSseClientTransport build() {
 			HttpClient httpClient = this.clientBuilder.connectTimeout(this.connectTimeout).build();
-			return new HttpClientSseClientTransport(httpClient, requestBuilder, baseUri, sseEndpoint, objectMapper,
-					httpRequestCustomizer);
+			return new HttpClientSseClientTransport(httpClient, requestBuilder, baseUri, sseEndpoint,
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, httpRequestCustomizer);
 		}
 
 	}
@@ -450,7 +375,7 @@ public Mono connect(Function, Mono> h
 								}
 							}
 							else if (MESSAGE_EVENT_TYPE.equals(responseEvent.sseEvent().event())) {
-								JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper,
+								JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper,
 										responseEvent.sseEvent().data());
 								sink.success();
 								return Flux.just(message);
@@ -531,7 +456,7 @@ public Mono sendMessage(JSONRPCMessage message) {
 	private Mono serializeMessage(final JSONRPCMessage message) {
 		return Mono.defer(() -> {
 			try {
-				return Mono.just(objectMapper.writeValueAsString(message));
+				return Mono.just(jsonMapper.writeValueAsString(message));
 			}
 			catch (IOException e) {
 				return Mono.error(new McpTransportException("Failed to serialize message", e));
@@ -582,8 +507,8 @@ public Mono closeGracefully() {
 	 * @return the unmarshalled object
 	 */
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return this.objectMapper.convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return this.jsonMapper.convertValue(data, typeRef);
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
index 4b1ff0d8b..c73515938 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
@@ -22,8 +22,8 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
+import io.modelcontextprotocol.json.McpJsonMapper;
 
 import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
@@ -106,7 +106,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	public static int BAD_REQUEST = 400;
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final URI baseUri;
 
@@ -124,10 +124,10 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private final AtomicReference> exceptionHandler = new AtomicReference<>();
 
-	private HttpClientStreamableHttpTransport(ObjectMapper objectMapper, HttpClient httpClient,
+	private HttpClientStreamableHttpTransport(McpJsonMapper jsonMapper, HttpClient httpClient,
 			HttpRequest.Builder requestBuilder, String baseUri, String endpoint, boolean resumableStreams,
 			boolean openConnectionOnStartup, McpAsyncHttpClientRequestCustomizer httpRequestCustomizer) {
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.httpClient = httpClient;
 		this.requestBuilder = requestBuilder;
 		this.baseUri = URI.create(baseUri);
@@ -278,7 +278,7 @@ private Mono reconnect(McpTransportStream stream) {
 											// won't since the next version considers
 											// removing it.
 											McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(
-													this.objectMapper, responseEvent.sseEvent().data());
+													this.jsonMapper, responseEvent.sseEvent().data());
 
 											Tuple2, Iterable> idWithMessages = Tuples
 												.of(Optional.ofNullable(responseEvent.sseEvent().id()),
@@ -393,7 +393,7 @@ else if (contentType.contains(APPLICATION_JSON)) {
 
 	public String toString(McpSchema.JSONRPCMessage message) {
 		try {
-			return this.objectMapper.writeValueAsString(message);
+			return this.jsonMapper.writeValueAsString(message);
 		}
 		catch (IOException e) {
 			throw new RuntimeException("Failed to serialize JSON-RPC message", e);
@@ -479,7 +479,7 @@ else if (contentType.contains(TEXT_EVENT_STREAM)) {
 									// since the
 									// next version considers removing it.
 									McpSchema.JSONRPCMessage message = McpSchema
-										.deserializeJsonRpcMessage(this.objectMapper, sseEvent.data());
+										.deserializeJsonRpcMessage(this.jsonMapper, sseEvent.data());
 
 									Tuple2, Iterable> idWithMessages = Tuples
 										.of(Optional.ofNullable(sseEvent.id()), List.of(message));
@@ -508,7 +508,7 @@ else if (contentType.contains(APPLICATION_JSON)) {
 						}
 
 						try {
-							return Mono.just(McpSchema.deserializeJsonRpcMessage(objectMapper, data));
+							return Mono.just(McpSchema.deserializeJsonRpcMessage(jsonMapper, data));
 						}
 						catch (IOException e) {
 							return Mono.error(new McpTransportException(
@@ -582,8 +582,8 @@ private static String sessionIdOrPlaceholder(McpTransportSession transportSes
 	}
 
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return this.objectMapper.convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return this.jsonMapper.convertValue(data, typeRef);
 	}
 
 	/**
@@ -593,7 +593,7 @@ public static class Builder {
 
 		private final String baseUri;
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private HttpClient.Builder clientBuilder = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1);
 
@@ -663,13 +663,13 @@ public Builder customizeRequest(final Consumer requestCusto
 		}
 
 		/**
-		 * Configure the {@link ObjectMapper} to use.
-		 * @param objectMapper instance to use
+		 * Configure a custom {@link McpJsonMapper} implementation to use.
+		 * @param jsonMapper instance to use
 		 * @return the builder instance
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "jsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -763,12 +763,10 @@ public Builder connectTimeout(Duration connectTimeout) {
 		 * @return a new instance of {@link HttpClientStreamableHttpTransport}
 		 */
 		public HttpClientStreamableHttpTransport build() {
-			ObjectMapper objectMapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
-
 			HttpClient httpClient = this.clientBuilder.connectTimeout(this.connectTimeout).build();
-
-			return new HttpClientStreamableHttpTransport(objectMapper, httpClient, requestBuilder, baseUri, endpoint,
-					resumableStreams, openConnectionOnStartup, httpRequestCustomizer);
+			return new HttpClientStreamableHttpTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					httpClient, requestBuilder, baseUri, endpoint, resumableStreams, openConnectionOnStartup,
+					httpRequestCustomizer);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java b/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
index 009d415e0..1b4eaca97 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
@@ -15,8 +15,8 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
+import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
@@ -48,7 +48,7 @@ public class StdioClientTransport implements McpClientTransport {
 	/** The server process being communicated with */
 	private Process process;
 
-	private ObjectMapper objectMapper;
+	private McpJsonMapper jsonMapper;
 
 	/** Scheduler for handling inbound messages from the server process */
 	private Scheduler inboundScheduler;
@@ -70,29 +70,20 @@ public class StdioClientTransport implements McpClientTransport {
 	private Consumer stdErrorHandler = error -> logger.info("STDERR Message received: {}", error);
 
 	/**
-	 * Creates a new StdioClientTransport with the specified parameters and default
-	 * ObjectMapper.
+	 * Creates a new StdioClientTransport with the specified parameters and JsonMapper.
 	 * @param params The parameters for configuring the server process
+	 * @param jsonMapper The JsonMapper to use for JSON serialization/deserialization
 	 */
-	public StdioClientTransport(ServerParameters params) {
-		this(params, new ObjectMapper());
-	}
-
-	/**
-	 * Creates a new StdioClientTransport with the specified parameters and ObjectMapper.
-	 * @param params The parameters for configuring the server process
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 */
-	public StdioClientTransport(ServerParameters params, ObjectMapper objectMapper) {
+	public StdioClientTransport(ServerParameters params, McpJsonMapper jsonMapper) {
 		Assert.notNull(params, "The params can not be null");
-		Assert.notNull(objectMapper, "The ObjectMapper can not be null");
+		Assert.notNull(jsonMapper, "The JsonMapper can not be null");
 
 		this.inboundSink = Sinks.many().unicast().onBackpressureBuffer();
 		this.outboundSink = Sinks.many().unicast().onBackpressureBuffer();
 
 		this.params = params;
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 
 		this.errorSink = Sinks.many().unicast().onBackpressureBuffer();
 
@@ -259,7 +250,7 @@ private void startInboundProcessing() {
 				String line;
 				while (!isClosing && (line = processReader.readLine()) != null) {
 					try {
-						JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(this.objectMapper, line);
+						JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(this.jsonMapper, line);
 						if (!this.inboundSink.tryEmitNext(message).isSuccess()) {
 							if (!isClosing) {
 								logger.error("Failed to enqueue inbound message: {}", message);
@@ -300,7 +291,7 @@ private void startOutboundProcessing() {
 			.handle((message, s) -> {
 				if (message != null && !isClosing) {
 					try {
-						String jsonMessage = objectMapper.writeValueAsString(message);
+						String jsonMessage = jsonMapper.writeValueAsString(message);
 						// Escape any embedded newlines in the JSON message as per spec:
 						// https://spec.modelcontextprotocol.io/specification/basic/transports/#stdio
 						// - Messages are delimited by newlines, and MUST NOT contain
@@ -392,8 +383,8 @@ public Sinks.Many getErrorSink() {
 	}
 
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return this.objectMapper.convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return this.jsonMapper.convertValue(data, typeRef);
 	}
 
 }
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index ba97174a0..38a16bd7e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -15,10 +15,16 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.BiFunction;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.DefaultMcpStreamableServerSessionFactory;
-import io.modelcontextprotocol.spec.JsonSchemaValidator;
+import io.modelcontextprotocol.spec.McpServerTransportProviderBase;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
+
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -90,7 +96,7 @@ public class McpAsyncServer {
 
 	private final McpServerTransportProviderBase mcpTransportProvider;
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final JsonSchemaValidator jsonSchemaValidator;
 
@@ -123,13 +129,13 @@ public class McpAsyncServer {
 	 * @param mcpTransportProvider The transport layer implementation for MCP
 	 * communication.
 	 * @param features The MCP server supported features.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * @param jsonMapper The JsonMapper to use for JSON serialization/deserialization
 	 */
-	McpAsyncServer(McpServerTransportProvider mcpTransportProvider, ObjectMapper objectMapper,
+	McpAsyncServer(McpServerTransportProvider mcpTransportProvider, McpJsonMapper jsonMapper,
 			McpServerFeatures.Async features, Duration requestTimeout,
 			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator) {
 		this.mcpTransportProvider = mcpTransportProvider;
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.serverInfo = features.serverInfo();
 		this.serverCapabilities = features.serverCapabilities().mutate().logging().build();
 		this.instructions = features.instructions();
@@ -150,11 +156,11 @@ public class McpAsyncServer {
 				requestTimeout, transport, this::asyncInitializeRequestHandler, requestHandlers, notificationHandlers));
 	}
 
-	McpAsyncServer(McpStreamableServerTransportProvider mcpTransportProvider, ObjectMapper objectMapper,
+	McpAsyncServer(McpStreamableServerTransportProvider mcpTransportProvider, McpJsonMapper jsonMapper,
 			McpServerFeatures.Async features, Duration requestTimeout,
 			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator) {
 		this.mcpTransportProvider = mcpTransportProvider;
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.serverInfo = features.serverInfo();
 		this.serverCapabilities = features.serverCapabilities().mutate().logging().build();
 		this.instructions = features.instructions();
@@ -505,8 +511,8 @@ private McpRequestHandler toolsListRequestHandler() {
 
 	private McpRequestHandler toolsCallRequestHandler() {
 		return (exchange, params) -> {
-			McpSchema.CallToolRequest callToolRequest = objectMapper.convertValue(params,
-					new TypeReference() {
+			McpSchema.CallToolRequest callToolRequest = jsonMapper.convertValue(params,
+					new TypeRef() {
 					});
 
 			Optional toolSpecification = this.tools.stream()
@@ -633,8 +639,8 @@ private List getResourceTemplates() {
 
 	private McpRequestHandler resourcesReadRequestHandler() {
 		return (exchange, params) -> {
-			McpSchema.ReadResourceRequest resourceRequest = objectMapper.convertValue(params,
-					new TypeReference() {
+			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params,
+					new TypeRef() {
 					});
 			var resourceUri = resourceRequest.uri();
 
@@ -742,8 +748,8 @@ private McpRequestHandler promptsListRequestHandler
 
 	private McpRequestHandler promptsGetRequestHandler() {
 		return (exchange, params) -> {
-			McpSchema.GetPromptRequest promptRequest = objectMapper.convertValue(params,
-					new TypeReference() {
+			McpSchema.GetPromptRequest promptRequest = jsonMapper.convertValue(params,
+					new TypeRef() {
 					});
 
 			// Implement prompt retrieval logic here
@@ -790,9 +796,8 @@ private McpRequestHandler setLoggerRequestHandler() {
 		return (exchange, params) -> {
 			return Mono.defer(() -> {
 
-				SetLevelRequest newMinLoggingLevel = objectMapper.convertValue(params,
-						new TypeReference() {
-						});
+				SetLevelRequest newMinLoggingLevel = jsonMapper.convertValue(params, new TypeRef() {
+				});
 
 				exchange.setMinLoggingLevel(newMinLoggingLevel.level());
 
@@ -914,4 +919,4 @@ void setProtocolVersions(List protocolVersions) {
 		this.protocolVersions = protocolVersions;
 	}
 
-}
\ No newline at end of file
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
index 1f0aebf02..a15c58cd5 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
@@ -8,7 +8,7 @@
 import java.util.ArrayList;
 import java.util.Collections;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpLoggableSession;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -37,16 +37,16 @@ public class McpAsyncServerExchange {
 
 	private final McpTransportContext transportContext;
 
-	private static final TypeReference CREATE_MESSAGE_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef CREATE_MESSAGE_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	private static final TypeReference LIST_ROOTS_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef LIST_ROOTS_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	private static final TypeReference ELICITATION_RESULT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef ELICITATION_RESULT_TYPE_REF = new TypeRef<>() {
 	};
 
-	public static final TypeReference OBJECT_TYPE_REF = new TypeReference<>() {
+	public static final TypeRef OBJECT_TYPE_REF = new TypeRef<>() {
 	};
 
 	/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
index 76a0de76b..ec86b5927 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -11,13 +11,13 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
 
-import io.modelcontextprotocol.spec.DefaultJsonSchemaValidator;
-import io.modelcontextprotocol.spec.JsonSchemaValidator;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
@@ -67,7 +67,7 @@
  * Example of creating a basic synchronous server: 
{@code
  * McpServer.sync(transportProvider)
  *     .serverInfo("my-server", "1.0.0")
- *     .tool(new Tool("calculator", "Performs calculations", schema),
+ *     .tool(Tool.builder().name("calculator").title("Performs calculations").inputSchema(schema).build(),
  *           (exchange, args) -> new CallToolResult("Result: " + calculate(args)))
  *     .build();
  * }

@@ -75,7 +75,7 @@
  * Example of creating a basic asynchronous server: 
{@code
  * McpServer.async(transportProvider)
  *     .serverInfo("my-server", "1.0.0")
- *     .tool(new Tool("calculator", "Performs calculations", schema),
+ *     .tool(Tool.builder().name("calculator").title("Performs calculations").inputSchema(schema).build(),
  *           (exchange, args) -> Mono.fromSupplier(() -> calculate(args))
  *               .map(result -> new CallToolResult("Result: " + result)))
  *     .build();
@@ -227,11 +227,12 @@ public McpAsyncServer build() {
 			var features = new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
 					this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers,
 					this.instructions);
-			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
-			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
-					: new DefaultJsonSchemaValidator(mapper);
-			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
+
+			var jsonSchemaValidator = (this.jsonSchemaValidator != null) ? this.jsonSchemaValidator
+					: JsonSchemaValidator.getDefault();
+
+			return new McpAsyncServer(transportProvider, jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					features, requestTimeout, uriTemplateManagerFactory, jsonSchemaValidator);
 		}
 
 	}
@@ -254,11 +255,10 @@ public McpAsyncServer build() {
 			var features = new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
 					this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers,
 					this.instructions);
-			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
-					: new DefaultJsonSchemaValidator(mapper);
-			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
+					: JsonSchemaValidator.getDefault();
+			return new McpAsyncServer(transportProvider, jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					features, requestTimeout, uriTemplateManagerFactory, jsonSchemaValidator);
 		}
 
 	}
@@ -270,7 +270,7 @@ abstract class AsyncSpecification> {
 
 		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
-		ObjectMapper objectMapper;
+		McpJsonMapper jsonMapper;
 
 		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
 
@@ -417,7 +417,7 @@ public AsyncSpecification capabilities(McpSchema.ServerCapabilities serverCap
 		 * 

 		 * Example usage: 
{@code
 		 * .tool(
-		 *     new Tool("calculator", "Performs calculations", schema),
+		 *     Tool.builder().name("calculator").title("Performs calculations").inputSchema(schema).build(),
 		 *     (exchange, args) -> Mono.fromSupplier(() -> calculate(args))
 		 *         .map(result -> new CallToolResult("Result: " + result))
 		 * )
@@ -765,14 +765,14 @@ public AsyncSpecification rootsChangeHandlers(
 		}
 
 		/**
-		 * Sets the object mapper to use for serializing and deserializing JSON messages.
-		 * @param objectMapper the instance to use. Must not be null.
+		 * Sets the JsonMapper to use for serializing and deserializing JSON messages.
+		 * @param jsonMapper the mapper to use. Must not be null.
 		 * @return This builder instance for method chaining.
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public AsyncSpecification objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public AsyncSpecification jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -813,13 +813,11 @@ public McpSyncServer build() {
 					this.rootsChangeHandlers, this.instructions);
 			McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures,
 					this.immediateExecution);
-			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
-			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
-					: new DefaultJsonSchemaValidator(mapper);
-
-			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
 
+			var asyncServer = new McpAsyncServer(transportProvider,
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, asyncFeatures, requestTimeout,
+					uriTemplateManagerFactory,
+					jsonSchemaValidator != null ? jsonSchemaValidator : JsonSchemaValidator.getDefault());
 			return new McpSyncServer(asyncServer, this.immediateExecution);
 		}
 
@@ -846,13 +844,11 @@ public McpSyncServer build() {
 					this.rootsChangeHandlers, this.instructions);
 			McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures,
 					this.immediateExecution);
-			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
-					: new DefaultJsonSchemaValidator(mapper);
-
-			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout,
+					: JsonSchemaValidator.getDefault();
+			var asyncServer = new McpAsyncServer(transportProvider,
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, asyncFeatures, this.requestTimeout,
 					this.uriTemplateManagerFactory, jsonSchemaValidator);
-
 			return new McpSyncServer(asyncServer, this.immediateExecution);
 		}
 
@@ -865,7 +861,7 @@ abstract class SyncSpecification> {
 
 		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
-		ObjectMapper objectMapper;
+		McpJsonMapper jsonMapper;
 
 		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
 
@@ -1014,7 +1010,7 @@ public SyncSpecification capabilities(McpSchema.ServerCapabilities serverCapa
 		 * 

 		 * Example usage: 
{@code
 		 * .tool(
-		 *     new Tool("calculator", "Performs calculations", schema),
+		 *     Tool.builder().name("calculator").title("Performs calculations".inputSchema(schema).build(),
 		 *     (exchange, args) -> new CallToolResult("Result: " + calculate(args))
 		 * )
 		 * }

@@ -1363,14 +1359,14 @@ public SyncSpecification rootsChangeHandlers(
 		}
 
 		/**
-		 * Sets the object mapper to use for serializing and deserializing JSON messages.
-		 * @param objectMapper the instance to use. Must not be null.
+		 * Sets the JsonMapper to use for serializing and deserializing JSON messages.
+		 * @param jsonMapper the mapper to use. Must not be null.
 		 * @return This builder instance for method chaining.
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public SyncSpecification objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public SyncSpecification jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -1404,7 +1400,7 @@ class StatelessAsyncSpecification {
 
 		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
-		ObjectMapper objectMapper;
+		McpJsonMapper jsonMapper;
 
 		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
 
@@ -1821,14 +1817,14 @@ public StatelessAsyncSpecification completions(
 		}
 
 		/**
-		 * Sets the object mapper to use for serializing and deserializing JSON messages.
-		 * @param objectMapper the instance to use. Must not be null.
+		 * Sets the JsonMapper to use for serializing and deserializing JSON messages.
+		 * @param jsonMapper the mapper to use. Must not be null.
 		 * @return This builder instance for method chaining.
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public StatelessAsyncSpecification objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public StatelessAsyncSpecification jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -1849,11 +1845,9 @@ public StatelessAsyncSpecification jsonSchemaValidator(JsonSchemaValidator jsonS
 		public McpStatelessAsyncServer build() {
 			var features = new McpStatelessServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
 					this.resources, this.resourceTemplates, this.prompts, this.completions, this.instructions);
-			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
-			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
-					: new DefaultJsonSchemaValidator(mapper);
-			return new McpStatelessAsyncServer(this.transport, mapper, features, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
+			return new McpStatelessAsyncServer(transport, jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					features, requestTimeout, uriTemplateManagerFactory,
+					jsonSchemaValidator != null ? jsonSchemaValidator : JsonSchemaValidator.getDefault());
 		}
 
 	}
@@ -1866,7 +1860,7 @@ class StatelessSyncSpecification {
 
 		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
 
-		ObjectMapper objectMapper;
+		McpJsonMapper jsonMapper;
 
 		McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
 
@@ -2283,14 +2277,14 @@ public StatelessSyncSpecification completions(
 		}
 
 		/**
-		 * Sets the object mapper to use for serializing and deserializing JSON messages.
-		 * @param objectMapper the instance to use. Must not be null.
+		 * Sets the JsonMapper to use for serializing and deserializing JSON messages.
+		 * @param jsonMapper the mapper to use. Must not be null.
 		 * @return This builder instance for method chaining.
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public StatelessSyncSpecification objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public StatelessSyncSpecification jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -2325,31 +2319,13 @@ public StatelessSyncSpecification immediateExecution(boolean immediateExecution)
 		}
 
 		public McpStatelessSyncServer build() {
-			/*
-			 * McpServerFeatures.Sync syncFeatures = new
-			 * McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities,
-			 * this.tools, this.resources, this.resourceTemplates, this.prompts,
-			 * this.completions, this.rootsChangeHandlers, this.instructions);
-			 * McpServerFeatures.Async asyncFeatures =
-			 * McpServerFeatures.Async.fromSync(syncFeatures, this.immediateExecution);
-			 * var mapper = this.objectMapper != null ? this.objectMapper : new
-			 * ObjectMapper(); var jsonSchemaValidator = this.jsonSchemaValidator != null
-			 * ? this.jsonSchemaValidator : new DefaultJsonSchemaValidator(mapper);
-			 *
-			 * var asyncServer = new McpAsyncServer(this.transportProvider, mapper,
-			 * asyncFeatures, this.requestTimeout, this.uriTemplateManagerFactory,
-			 * jsonSchemaValidator);
-			 *
-			 * return new McpSyncServer(asyncServer, this.immediateExecution);
-			 */
 			var syncFeatures = new McpStatelessServerFeatures.Sync(this.serverInfo, this.serverCapabilities, this.tools,
 					this.resources, this.resourceTemplates, this.prompts, this.completions, this.instructions);
 			var asyncFeatures = McpStatelessServerFeatures.Async.fromSync(syncFeatures, this.immediateExecution);
-			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
-			var jsonSchemaValidator = this.jsonSchemaValidator != null ? this.jsonSchemaValidator
-					: new DefaultJsonSchemaValidator(mapper);
-			var asyncServer = new McpStatelessAsyncServer(this.transport, mapper, asyncFeatures, this.requestTimeout,
-					this.uriTemplateManagerFactory, jsonSchemaValidator);
+			var asyncServer = new McpStatelessAsyncServer(transport,
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, asyncFeatures, requestTimeout,
+					uriTemplateManagerFactory,
+					this.jsonSchemaValidator != null ? this.jsonSchemaValidator : JsonSchemaValidator.getDefault());
 			return new McpStatelessSyncServer(asyncServer, this.immediateExecution);
 		}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
index 12edfb341..cc3fae689 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
@@ -453,12 +453,13 @@ static AsyncCompletionSpecification fromSync(SyncCompletionSpecification complet
 	 *
 	 * 
{@code
 	 * McpServerFeatures.SyncToolSpecification.builder()
-	 * 		.tool(new Tool(
-	 * 				"calculator",
-	 * 				"Performs mathematical calculations",
-	 * 				new JsonSchemaObject()
+	 * 		.tool(Tool.builder()
+	 * 				.name("calculator")
+	 * 				.title("Performs mathematical calculations")
+	 * 				.inputSchema(new JsonSchemaObject()
 	 * 						.required("expression")
-	 * 						.property("expression", JsonSchemaType.STRING)))
+	 * 						.property("expression", JsonSchemaType.STRING))
+	 * 				.build()
 	 * 		.toolHandler((exchange, req) -> {
 	 * 			String expr = (String) req.arguments().get("expression");
 	 * 			return new CallToolResult("Result: " + evaluate(expr));
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index ee5a4d354..8f79d8c68 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -4,16 +4,15 @@
 
 package io.modelcontextprotocol.server;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
+import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.common.McpTransportContext;
-import io.modelcontextprotocol.spec.JsonSchemaValidator;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse;
 import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
-import io.modelcontextprotocol.spec.McpSchema.TextContent;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpStatelessServerTransport;
 import io.modelcontextprotocol.util.Assert;
@@ -48,7 +47,7 @@ public class McpStatelessAsyncServer {
 
 	private final McpStatelessServerTransport mcpTransportProvider;
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final McpSchema.ServerCapabilities serverCapabilities;
 
@@ -72,11 +71,11 @@ public class McpStatelessAsyncServer {
 
 	private final JsonSchemaValidator jsonSchemaValidator;
 
-	McpStatelessAsyncServer(McpStatelessServerTransport mcpTransport, ObjectMapper objectMapper,
+	McpStatelessAsyncServer(McpStatelessServerTransport mcpTransport, McpJsonMapper jsonMapper,
 			McpStatelessServerFeatures.Async features, Duration requestTimeout,
 			McpUriTemplateManagerFactory uriTemplateManagerFactory, JsonSchemaValidator jsonSchemaValidator) {
 		this.mcpTransportProvider = mcpTransport;
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.serverInfo = features.serverInfo();
 		this.serverCapabilities = features.serverCapabilities();
 		this.instructions = features.instructions();
@@ -132,7 +131,7 @@ public class McpStatelessAsyncServer {
 	// ---------------------------------------
 	private McpStatelessRequestHandler asyncInitializeRequestHandler() {
 		return (ctx, req) -> Mono.defer(() -> {
-			McpSchema.InitializeRequest initializeRequest = this.objectMapper.convertValue(req,
+			McpSchema.InitializeRequest initializeRequest = this.jsonMapper.convertValue(req,
 					McpSchema.InitializeRequest.class);
 
 			logger.info("Client initialize request - Protocol: {}, Capabilities: {}, Info: {}",
@@ -376,8 +375,8 @@ private McpStatelessRequestHandler toolsListRequestHa
 
 	private McpStatelessRequestHandler toolsCallRequestHandler() {
 		return (ctx, params) -> {
-			McpSchema.CallToolRequest callToolRequest = objectMapper.convertValue(params,
-					new TypeReference() {
+			McpSchema.CallToolRequest callToolRequest = jsonMapper.convertValue(params,
+					new TypeRef() {
 					});
 
 			Optional toolSpecification = this.tools.stream()
@@ -479,8 +478,8 @@ private List getResourceTemplates() {
 
 	private McpStatelessRequestHandler resourcesReadRequestHandler() {
 		return (ctx, params) -> {
-			McpSchema.ReadResourceRequest resourceRequest = objectMapper.convertValue(params,
-					new TypeReference() {
+			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params,
+					new TypeRef() {
 					});
 			var resourceUri = resourceRequest.uri();
 
@@ -569,8 +568,8 @@ private McpStatelessRequestHandler promptsListReque
 
 	private McpStatelessRequestHandler promptsGetRequestHandler() {
 		return (ctx, params) -> {
-			McpSchema.GetPromptRequest promptRequest = objectMapper.convertValue(params,
-					new TypeReference() {
+			McpSchema.GetPromptRequest promptRequest = jsonMapper.convertValue(params,
+					new TypeRef() {
 					});
 
 			// Implement prompt retrieval logic here
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index bbc1edf24..4739e231a 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -14,8 +14,8 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicBoolean;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
@@ -89,8 +89,8 @@ public class HttpServletSseServerTransportProvider extends HttpServlet implement
 
 	public static final String DEFAULT_BASE_URL = "";
 
-	/** JSON object mapper for serialization/deserialization */
-	private final ObjectMapper objectMapper;
+	/** JSON mapper for serialization/deserialization */
+	private final McpJsonMapper jsonMapper;
 
 	/** Base URL for the server transport */
 	private final String baseUrl;
@@ -121,60 +121,7 @@ public class HttpServletSseServerTransportProvider extends HttpServlet implement
 	/**
 	 * Creates a new HttpServletSseServerTransportProvider instance with a custom SSE
 	 * endpoint.
-	 * @param objectMapper The JSON object mapper to use for message
-	 * serialization/deserialization
-	 * @param messageEndpoint The endpoint path where clients will send their messages
-	 * @param sseEndpoint The endpoint path where clients will establish SSE connections
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint,
-			String sseEndpoint) {
-		this(objectMapper, DEFAULT_BASE_URL, messageEndpoint, sseEndpoint);
-	}
-
-	/**
-	 * Creates a new HttpServletSseServerTransportProvider instance with a custom SSE
-	 * endpoint.
-	 * @param objectMapper The JSON object mapper to use for message
-	 * serialization/deserialization
-	 * @param baseUrl The base URL for the server transport
-	 * @param messageEndpoint The endpoint path where clients will send their messages
-	 * @param sseEndpoint The endpoint path where clients will establish SSE connections
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
-			String sseEndpoint) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, null, (serverRequest) -> McpTransportContext.EMPTY);
-	}
-
-	/**
-	 * Creates a new HttpServletSseServerTransportProvider instance with a custom SSE
-	 * endpoint.
-	 * @param objectMapper The JSON object mapper to use for message
-	 * serialization/deserialization
-	 * @param baseUrl The base URL for the server transport
-	 * @param messageEndpoint The endpoint path where clients will send their messages
-	 * @param sseEndpoint The endpoint path where clients will establish SSE connections
-	 * @param keepAliveInterval The interval for keep-alive pings, or null to disable
-	 * keep-alive functionality
-	 * @deprecated Use the builder {@link #builder()} instead for better configuration
-	 * options.
-	 */
-	@Deprecated
-	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
-			String sseEndpoint, Duration keepAliveInterval) {
-		this(objectMapper, baseUrl, messageEndpoint, sseEndpoint, keepAliveInterval,
-				(serverRequest) -> McpTransportContext.EMPTY);
-	}
-
-	/**
-	 * Creates a new HttpServletSseServerTransportProvider instance with a custom SSE
-	 * endpoint.
-	 * @param objectMapper The JSON object mapper to use for message
+	 * @param jsonMapper The JSON object mapper to use for message
 	 * serialization/deserialization
 	 * @param baseUrl The base URL for the server transport
 	 * @param messageEndpoint The endpoint path where clients will send their messages
@@ -185,16 +132,16 @@ public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String b
 	 * @deprecated Use the builder {@link #builder()} instead for better configuration
 	 * options.
 	 */
-	private HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String baseUrl, String messageEndpoint,
+	private HttpServletSseServerTransportProvider(McpJsonMapper jsonMapper, String baseUrl, String messageEndpoint,
 			String sseEndpoint, Duration keepAliveInterval,
 			McpTransportContextExtractor contextExtractor) {
 
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(jsonMapper, "JsonMapper must not be null");
 		Assert.notNull(messageEndpoint, "messageEndpoint must not be null");
 		Assert.notNull(sseEndpoint, "sseEndpoint must not be null");
 		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.baseUrl = baseUrl;
 		this.messageEndpoint = messageEndpoint;
 		this.sseEndpoint = sseEndpoint;
@@ -217,17 +164,6 @@ public List protocolVersions() {
 		return List.of(ProtocolVersions.MCP_2024_11_05);
 	}
 
-	/**
-	 * Creates a new HttpServletSseServerTransportProvider instance with the default SSE
-	 * endpoint.
-	 * @param objectMapper The JSON object mapper to use for message
-	 * serialization/deserialization
-	 * @param messageEndpoint The endpoint path where clients will send their messages
-	 */
-	public HttpServletSseServerTransportProvider(ObjectMapper objectMapper, String messageEndpoint) {
-		this(objectMapper, messageEndpoint, DEFAULT_SSE_ENDPOINT);
-	}
-
 	/**
 	 * Sets the session factory for creating new sessions.
 	 * @param sessionFactory The session factory to use
@@ -342,7 +278,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			response.setContentType(APPLICATION_JSON);
 			response.setCharacterEncoding(UTF_8);
 			response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
-			String jsonError = objectMapper.writeValueAsString(new McpError("Session ID missing in message endpoint"));
+			String jsonError = jsonMapper.writeValueAsString(new McpError("Session ID missing in message endpoint"));
 			PrintWriter writer = response.getWriter();
 			writer.write(jsonError);
 			writer.flush();
@@ -355,7 +291,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			response.setContentType(APPLICATION_JSON);
 			response.setCharacterEncoding(UTF_8);
 			response.setStatus(HttpServletResponse.SC_NOT_FOUND);
-			String jsonError = objectMapper.writeValueAsString(new McpError("Session not found: " + sessionId));
+			String jsonError = jsonMapper.writeValueAsString(new McpError("Session not found: " + sessionId));
 			PrintWriter writer = response.getWriter();
 			writer.write(jsonError);
 			writer.flush();
@@ -371,7 +307,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 			}
 
 			final McpTransportContext transportContext = this.contextExtractor.extract(request);
-			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body.toString());
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body.toString());
 
 			// Process the message through the session's handle method
 			// Block for Servlet compatibility
@@ -386,7 +322,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 				response.setContentType(APPLICATION_JSON);
 				response.setCharacterEncoding(UTF_8);
 				response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
-				String jsonError = objectMapper.writeValueAsString(mcpError);
+				String jsonError = jsonMapper.writeValueAsString(mcpError);
 				PrintWriter writer = response.getWriter();
 				writer.write(jsonError);
 				writer.flush();
@@ -482,7 +418,7 @@ private class HttpServletMcpSessionTransport implements McpServerTransport {
 		public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			return Mono.fromRunnable(() -> {
 				try {
-					String jsonText = objectMapper.writeValueAsString(message);
+					String jsonText = jsonMapper.writeValueAsString(message);
 					sendEvent(writer, MESSAGE_EVENT_TYPE, jsonText);
 					logger.debug("Message sent to session {}", sessionId);
 				}
@@ -495,15 +431,15 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 		}
 
 		/**
-		 * Converts data from one type to another using the configured ObjectMapper.
+		 * Converts data from one type to another using the configured JsonMapper.
 		 * @param data The source data object to convert
 		 * @param typeRef The target type reference
 		 * @return The converted object of type T
 		 * @param  The target type
 		 */
 		@Override
-		public  T unmarshalFrom(Object data, TypeReference typeRef) {
-			return objectMapper.convertValue(data, typeRef);
+		public  T unmarshalFrom(Object data, TypeRef typeRef) {
+			return jsonMapper.convertValue(data, typeRef);
 		}
 
 		/**
@@ -559,7 +495,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper = new ObjectMapper();
+		private McpJsonMapper jsonMapper;
 
 		private String baseUrl = DEFAULT_BASE_URL;
 
@@ -573,13 +509,15 @@ public static class Builder {
 		private Duration keepAliveInterval;
 
 		/**
-		 * Sets the JSON object mapper to use for message serialization/deserialization.
-		 * @param objectMapper The object mapper to use
+		 * Sets the JsonMapper implementation to use for serialization/deserialization. If
+		 * not specified, a JacksonJsonMapper will be created from the configured
+		 * ObjectMapper.
+		 * @param jsonMapper The JsonMapper to use
 		 * @return This builder instance for method chaining
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -648,16 +586,14 @@ public Builder keepAliveInterval(Duration keepAliveInterval) {
 		 * Builds a new instance of HttpServletSseServerTransportProvider with the
 		 * configured settings.
 		 * @return A new HttpServletSseServerTransportProvider instance
-		 * @throws IllegalStateException if objectMapper or messageEndpoint is not set
+		 * @throws IllegalStateException if jsonMapper or messageEndpoint is not set
 		 */
 		public HttpServletSseServerTransportProvider build() {
-			if (objectMapper == null) {
-				throw new IllegalStateException("ObjectMapper must be set");
-			}
 			if (messageEndpoint == null) {
 				throw new IllegalStateException("MessageEndpoint must be set");
 			}
-			return new HttpServletSseServerTransportProvider(objectMapper, baseUrl, messageEndpoint, sseEndpoint,
+			return new HttpServletSseServerTransportProvider(
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, baseUrl, messageEndpoint, sseEndpoint,
 					keepAliveInterval, contextExtractor);
 		}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
index 9a8f6cbb9..40767f416 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
@@ -11,7 +11,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
 
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpStatelessServerHandler;
@@ -48,7 +48,7 @@ public class HttpServletStatelessServerTransport extends HttpServlet implements
 
 	public static final String FAILED_TO_SEND_ERROR_RESPONSE = "Failed to send error response: {}";
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final String mcpEndpoint;
 
@@ -58,13 +58,13 @@ public class HttpServletStatelessServerTransport extends HttpServlet implements
 
 	private volatile boolean isClosing = false;
 
-	private HttpServletStatelessServerTransport(ObjectMapper objectMapper, String mcpEndpoint,
+	private HttpServletStatelessServerTransport(McpJsonMapper jsonMapper, String mcpEndpoint,
 			McpTransportContextExtractor contextExtractor) {
-		Assert.notNull(objectMapper, "objectMapper must not be null");
+		Assert.notNull(jsonMapper, "jsonMapper must not be null");
 		Assert.notNull(mcpEndpoint, "mcpEndpoint must not be null");
 		Assert.notNull(contextExtractor, "contextExtractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.mcpEndpoint = mcpEndpoint;
 		this.contextExtractor = contextExtractor;
 	}
@@ -139,7 +139,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 				body.append(line);
 			}
 
-			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body.toString());
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body.toString());
 
 			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
 				try {
@@ -152,7 +152,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 					response.setCharacterEncoding(UTF_8);
 					response.setStatus(HttpServletResponse.SC_OK);
 
-					String jsonResponseText = objectMapper.writeValueAsString(jsonrpcResponse);
+					String jsonResponseText = jsonMapper.writeValueAsString(jsonrpcResponse);
 					PrintWriter writer = response.getWriter();
 					writer.write(jsonResponseText);
 					writer.flush();
@@ -203,7 +203,7 @@ private void responseError(HttpServletResponse response, int httpCode, McpError
 		response.setContentType(APPLICATION_JSON);
 		response.setCharacterEncoding(UTF_8);
 		response.setStatus(httpCode);
-		String jsonError = objectMapper.writeValueAsString(mcpError);
+		String jsonError = jsonMapper.writeValueAsString(mcpError);
 		PrintWriter writer = response.getWriter();
 		writer.write(jsonError);
 		writer.flush();
@@ -236,7 +236,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private String mcpEndpoint = "/mcp";
 
@@ -248,15 +248,15 @@ private Builder() {
 		}
 
 		/**
-		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * Sets the JsonMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
-		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @param jsonMapper The JsonMapper instance. Must not be null.
 		 * @return this builder instance
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if jsonMapper is null
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -295,10 +295,9 @@ public Builder contextExtractor(McpTransportContextExtractor
 		 * @throws IllegalStateException if required parameters are not set
 		 */
 		public HttpServletStatelessServerTransport build() {
-			Assert.notNull(objectMapper, "ObjectMapper must be set");
 			Assert.notNull(mcpEndpoint, "Message endpoint must be set");
-
-			return new HttpServletStatelessServerTransport(objectMapper, mcpEndpoint, contextExtractor);
+			return new HttpServletStatelessServerTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+					mcpEndpoint, contextExtractor);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
index 3cb8d7b15..137015876 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
@@ -16,8 +16,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
@@ -29,6 +28,7 @@
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
 import jakarta.servlet.AsyncContext;
 import jakarta.servlet.ServletException;
@@ -97,7 +97,7 @@ public class HttpServletStreamableServerTransportProvider extends HttpServlet
 	 */
 	private final boolean disallowDelete;
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private McpStreamableServerSession.Factory sessionFactory;
 
@@ -121,22 +121,22 @@ public class HttpServletStreamableServerTransportProvider extends HttpServlet
 
 	/**
 	 * Constructs a new HttpServletStreamableServerTransportProvider instance.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
-	 * of messages.
+	 * @param jsonMapper The JsonMapper to use for JSON serialization/deserialization of
+	 * messages.
 	 * @param mcpEndpoint The endpoint URI where clients should send their JSON-RPC
 	 * messages via HTTP. This endpoint will handle GET, POST, and DELETE requests.
 	 * @param disallowDelete Whether to disallow DELETE requests on the endpoint.
 	 * @param contextExtractor The extractor for transport context from the request.
 	 * @throws IllegalArgumentException if any parameter is null
 	 */
-	private HttpServletStreamableServerTransportProvider(ObjectMapper objectMapper, String mcpEndpoint,
+	private HttpServletStreamableServerTransportProvider(McpJsonMapper jsonMapper, String mcpEndpoint,
 			boolean disallowDelete, McpTransportContextExtractor contextExtractor,
 			Duration keepAliveInterval) {
-		Assert.notNull(objectMapper, "ObjectMapper must not be null");
+		Assert.notNull(jsonMapper, "JsonMapper must not be null");
 		Assert.notNull(mcpEndpoint, "MCP endpoint must not be null");
 		Assert.notNull(contextExtractor, "Context extractor must not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.mcpEndpoint = mcpEndpoint;
 		this.disallowDelete = disallowDelete;
 		this.contextExtractor = contextExtractor;
@@ -392,7 +392,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 				body.append(line);
 			}
 
-			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper, body.toString());
+			McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper, body.toString());
 
 			// Handle initialization request
 			if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest
@@ -403,8 +403,8 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 					return;
 				}
 
-				McpSchema.InitializeRequest initializeRequest = objectMapper.convertValue(jsonrpcRequest.params(),
-						new TypeReference() {
+				McpSchema.InitializeRequest initializeRequest = jsonMapper.convertValue(jsonrpcRequest.params(),
+						new TypeRef() {
 						});
 				McpStreamableServerSession.McpStreamableServerSessionInit init = this.sessionFactory
 					.startSession(initializeRequest);
@@ -418,7 +418,7 @@ protected void doPost(HttpServletRequest request, HttpServletResponse response)
 					response.setHeader(HttpHeaders.MCP_SESSION_ID, init.session().getId());
 					response.setStatus(HttpServletResponse.SC_OK);
 
-					String jsonResponse = objectMapper.writeValueAsString(new McpSchema.JSONRPCResponse(
+					String jsonResponse = jsonMapper.writeValueAsString(new McpSchema.JSONRPCResponse(
 							McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), initResult, null));
 
 					PrintWriter writer = response.getWriter();
@@ -578,7 +578,7 @@ public void responseError(HttpServletResponse response, int httpCode, McpError m
 		response.setContentType(APPLICATION_JSON);
 		response.setCharacterEncoding(UTF_8);
 		response.setStatus(httpCode);
-		String jsonError = objectMapper.writeValueAsString(mcpError);
+		String jsonError = jsonMapper.writeValueAsString(mcpError);
 		PrintWriter writer = response.getWriter();
 		writer.write(jsonError);
 		writer.flush();
@@ -685,7 +685,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId
 						return;
 					}
 
-					String jsonText = objectMapper.writeValueAsString(message);
+					String jsonText = jsonMapper.writeValueAsString(message);
 					HttpServletStreamableServerTransportProvider.this.sendEvent(writer, MESSAGE_EVENT_TYPE, jsonText,
 							messageId != null ? messageId : this.sessionId);
 					logger.debug("Message sent to session {} with ID {}", this.sessionId, messageId);
@@ -702,15 +702,15 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message, String messageId
 		}
 
 		/**
-		 * Converts data from one type to another using the configured ObjectMapper.
+		 * Converts data from one type to another using the configured JsonMapper.
 		 * @param data The source data object to convert
 		 * @param typeRef The target type reference
 		 * @return The converted object of type T
 		 * @param  The target type
 		 */
 		@Override
-		public  T unmarshalFrom(Object data, TypeReference typeRef) {
-			return objectMapper.convertValue(data, typeRef);
+		public  T unmarshalFrom(Object data, TypeRef typeRef) {
+			return jsonMapper.convertValue(data, typeRef);
 		}
 
 		/**
@@ -762,7 +762,7 @@ public static Builder builder() {
 	 */
 	public static class Builder {
 
-		private ObjectMapper objectMapper;
+		private McpJsonMapper jsonMapper;
 
 		private String mcpEndpoint = "/mcp";
 
@@ -774,15 +774,15 @@ public static class Builder {
 		private Duration keepAliveInterval;
 
 		/**
-		 * Sets the ObjectMapper to use for JSON serialization/deserialization of MCP
+		 * Sets the JsonMapper to use for JSON serialization/deserialization of MCP
 		 * messages.
-		 * @param objectMapper The ObjectMapper instance. Must not be null.
+		 * @param jsonMapper The JsonMapper instance. Must not be null.
 		 * @return this builder instance
-		 * @throws IllegalArgumentException if objectMapper is null
+		 * @throws IllegalArgumentException if JsonMapper is null
 		 */
-		public Builder objectMapper(ObjectMapper objectMapper) {
-			Assert.notNull(objectMapper, "ObjectMapper must not be null");
-			this.objectMapper = objectMapper;
+		public Builder jsonMapper(McpJsonMapper jsonMapper) {
+			Assert.notNull(jsonMapper, "JsonMapper must not be null");
+			this.jsonMapper = jsonMapper;
 			return this;
 		}
 
@@ -839,11 +839,10 @@ public Builder keepAliveInterval(Duration keepAliveInterval) {
 		 * @throws IllegalStateException if required parameters are not set
 		 */
 		public HttpServletStreamableServerTransportProvider build() {
-			Assert.notNull(this.objectMapper, "ObjectMapper must be set");
 			Assert.notNull(this.mcpEndpoint, "MCP endpoint must be set");
-
-			return new HttpServletStreamableServerTransportProvider(this.objectMapper, this.mcpEndpoint,
-					this.disallowDelete, this.contextExtractor, this.keepAliveInterval);
+			return new HttpServletStreamableServerTransportProvider(
+					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, mcpEndpoint, disallowDelete,
+					contextExtractor, keepAliveInterval);
 		}
 
 	}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
index af602f610..68be62931 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
@@ -15,8 +15,7 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.function.Function;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
@@ -25,6 +24,7 @@
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.json.McpJsonMapper;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
@@ -44,7 +44,7 @@ public class StdioServerTransportProvider implements McpServerTransportProvider
 
 	private static final Logger logger = LoggerFactory.getLogger(StdioServerTransportProvider.class);
 
-	private final ObjectMapper objectMapper;
+	private final McpJsonMapper jsonMapper;
 
 	private final InputStream inputStream;
 
@@ -56,36 +56,28 @@ public class StdioServerTransportProvider implements McpServerTransportProvider
 
 	private final Sinks.One inboundReady = Sinks.one();
 
-	/**
-	 * Creates a new StdioServerTransportProvider with a default ObjectMapper and System
-	 * streams.
-	 */
-	public StdioServerTransportProvider() {
-		this(new ObjectMapper());
-	}
-
 	/**
 	 * Creates a new StdioServerTransportProvider with the specified ObjectMapper and
 	 * System streams.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * @param jsonMapper The JsonMapper to use for JSON serialization/deserialization
 	 */
-	public StdioServerTransportProvider(ObjectMapper objectMapper) {
-		this(objectMapper, System.in, System.out);
+	public StdioServerTransportProvider(McpJsonMapper jsonMapper) {
+		this(jsonMapper, System.in, System.out);
 	}
 
 	/**
 	 * Creates a new StdioServerTransportProvider with the specified ObjectMapper and
 	 * streams.
-	 * @param objectMapper The ObjectMapper to use for JSON serialization/deserialization
+	 * @param jsonMapper The JsonMapper to use for JSON serialization/deserialization
 	 * @param inputStream The input stream to read from
 	 * @param outputStream The output stream to write to
 	 */
-	public StdioServerTransportProvider(ObjectMapper objectMapper, InputStream inputStream, OutputStream outputStream) {
-		Assert.notNull(objectMapper, "The ObjectMapper can not be null");
+	public StdioServerTransportProvider(McpJsonMapper jsonMapper, InputStream inputStream, OutputStream outputStream) {
+		Assert.notNull(jsonMapper, "The JsonMapper can not be null");
 		Assert.notNull(inputStream, "The InputStream can not be null");
 		Assert.notNull(outputStream, "The OutputStream can not be null");
 
-		this.objectMapper = objectMapper;
+		this.jsonMapper = jsonMapper;
 		this.inputStream = inputStream;
 		this.outputStream = outputStream;
 	}
@@ -165,8 +157,8 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 		}
 
 		@Override
-		public  T unmarshalFrom(Object data, TypeReference typeRef) {
-			return objectMapper.convertValue(data, typeRef);
+		public  T unmarshalFrom(Object data, TypeRef typeRef) {
+			return jsonMapper.convertValue(data, typeRef);
 		}
 
 		@Override
@@ -219,7 +211,7 @@ private void startInboundProcessing() {
 								logger.debug("Received JSON message: {}", line);
 
 								try {
-									McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(objectMapper,
+									McpSchema.JSONRPCMessage message = McpSchema.deserializeJsonRpcMessage(jsonMapper,
 											line);
 									if (!this.inboundSink.tryEmitNext(message).isSuccess()) {
 										// logIfNotClosing("Failed to enqueue message");
@@ -263,7 +255,7 @@ private void startOutboundProcessing() {
 				 .handle((message, sink) -> {
 					 if (message != null && !isClosing.get()) {
 						 try {
-							 String jsonMessage = objectMapper.writeValueAsString(message);
+							 String jsonMessage = jsonMapper.writeValueAsString(message);
 							 // Escape any embedded newlines in the JSON message as per spec
 							 jsonMessage = jsonMessage.replace("\r\n", "\\n").replace("\n", "\\n").replace("\r", "\\n");
 	
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
index 6ac8defa0..bc3f53467 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
@@ -4,7 +4,7 @@
 
 package io.modelcontextprotocol.spec;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.util.Assert;
 import org.reactivestreams.Publisher;
 import org.slf4j.Logger;
@@ -254,7 +254,7 @@ private String generateRequestId() {
 	 * @return A Mono containing the response
 	 */
 	@Override
-	public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+	public  Mono sendRequest(String method, Object requestParams, TypeRef typeRef) {
 		String requestId = this.generateRequestId();
 
 		return Mono.deferContextual(ctx -> Mono.create(pendingResponseSink -> {
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index ea823b04b..32b2bae36 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -18,8 +18,9 @@
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
 import com.fasterxml.jackson.annotation.JsonTypeInfo.As;
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
+
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -109,8 +110,6 @@ private McpSchema() {
 	// Elicitation Methods
 	public static final String METHOD_ELICITATION_CREATE = "elicitation/create";
 
-	private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
-
 	// ---------------------------
 	// JSON-RPC Error Codes
 	// ---------------------------
@@ -176,12 +175,12 @@ public sealed interface Notification
 
 	}
 
-	private static final TypeReference> MAP_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef> MAP_TYPE_REF = new TypeRef<>() {
 	};
 
 	/**
 	 * Deserializes a JSON string into a JSONRPCMessage object.
-	 * @param objectMapper The ObjectMapper instance to use for deserialization
+	 * @param jsonMapper The JsonMapper instance to use for deserialization
 	 * @param jsonText The JSON string to deserialize
 	 * @return A JSONRPCMessage instance using either the {@link JSONRPCRequest},
 	 * {@link JSONRPCNotification}, or {@link JSONRPCResponse} classes.
@@ -189,22 +188,22 @@ public sealed interface Notification
 	 * @throws IllegalArgumentException If the JSON structure doesn't match any known
 	 * message type
 	 */
-	public static JSONRPCMessage deserializeJsonRpcMessage(ObjectMapper objectMapper, String jsonText)
+	public static JSONRPCMessage deserializeJsonRpcMessage(McpJsonMapper jsonMapper, String jsonText)
 			throws IOException {
 
 		logger.debug("Received JSON message: {}", jsonText);
 
-		var map = objectMapper.readValue(jsonText, MAP_TYPE_REF);
+		var map = jsonMapper.readValue(jsonText, MAP_TYPE_REF);
 
 		// Determine message type based on specific JSON structure
 		if (map.containsKey("method") && map.containsKey("id")) {
-			return objectMapper.convertValue(map, JSONRPCRequest.class);
+			return jsonMapper.convertValue(map, JSONRPCRequest.class);
 		}
 		else if (map.containsKey("method") && !map.containsKey("id")) {
-			return objectMapper.convertValue(map, JSONRPCNotification.class);
+			return jsonMapper.convertValue(map, JSONRPCNotification.class);
 		}
 		else if (map.containsKey("result") || map.containsKey("error")) {
-			return objectMapper.convertValue(map, JSONRPCResponse.class);
+			return jsonMapper.convertValue(map, JSONRPCResponse.class);
 		}
 
 		throw new IllegalArgumentException("Cannot deserialize JSONRPCMessage: " + jsonText);
@@ -1270,53 +1269,6 @@ public record Tool( // @formatter:off
 		@JsonProperty("annotations") ToolAnnotations annotations,
 		@JsonProperty("_meta") Map meta) { // @formatter:on
 
-		/**
-		 * @deprecated Only exists for backwards-compatibility purposes. Use
-		 * {@link Tool#builder()} instead.
-		 */
-		@Deprecated
-		public Tool(String name, String description, JsonSchema inputSchema, ToolAnnotations annotations) {
-			this(name, null, description, inputSchema, null, annotations, null);
-		}
-
-		/**
-		 * @deprecated Only exists for backwards-compatibility purposes. Use
-		 * {@link Tool#builder()} instead.
-		 */
-		@Deprecated
-		public Tool(String name, String description, String inputSchema) {
-			this(name, null, description, parseSchema(inputSchema), null, null, null);
-		}
-
-		/**
-		 * @deprecated Only exists for backwards-compatibility purposes. Use
-		 * {@link Tool#builder()} instead.
-		 */
-		@Deprecated
-		public Tool(String name, String description, String schema, ToolAnnotations annotations) {
-			this(name, null, description, parseSchema(schema), null, annotations, null);
-		}
-
-		/**
-		 * @deprecated Only exists for backwards-compatibility purposes. Use
-		 * {@link Tool#builder()} instead.
-		 */
-		@Deprecated
-		public Tool(String name, String description, String inputSchema, String outputSchema,
-				ToolAnnotations annotations) {
-			this(name, null, description, parseSchema(inputSchema), schemaToMap(outputSchema), annotations, null);
-		}
-
-		/**
-		 * @deprecated Only exists for backwards-compatibility purposes. Use
-		 * {@link Tool#builder()} instead.
-		 */
-		@Deprecated
-		public Tool(String name, String title, String description, String inputSchema, String outputSchema,
-				ToolAnnotations annotations) {
-			this(name, title, description, parseSchema(inputSchema), schemaToMap(outputSchema), annotations, null);
-		}
-
 		public static Builder builder() {
 			return new Builder();
 		}
@@ -1357,8 +1309,8 @@ public Builder inputSchema(JsonSchema inputSchema) {
 				return this;
 			}
 
-			public Builder inputSchema(String inputSchema) {
-				this.inputSchema = parseSchema(inputSchema);
+			public Builder inputSchema(McpJsonMapper jsonMapper, String inputSchema) {
+				this.inputSchema = parseSchema(jsonMapper, inputSchema);
 				return this;
 			}
 
@@ -1367,8 +1319,8 @@ public Builder outputSchema(Map outputSchema) {
 				return this;
 			}
 
-			public Builder outputSchema(String outputSchema) {
-				this.outputSchema = schemaToMap(outputSchema);
+			public Builder outputSchema(McpJsonMapper jsonMapper, String outputSchema) {
+				this.outputSchema = schemaToMap(jsonMapper, outputSchema);
 				return this;
 			}
 
@@ -1390,18 +1342,18 @@ public Tool build() {
 		}
 	}
 
-	private static Map schemaToMap(String schema) {
+	private static Map schemaToMap(McpJsonMapper jsonMapper, String schema) {
 		try {
-			return OBJECT_MAPPER.readValue(schema, MAP_TYPE_REF);
+			return jsonMapper.readValue(schema, MAP_TYPE_REF);
 		}
 		catch (IOException e) {
 			throw new IllegalArgumentException("Invalid schema: " + schema, e);
 		}
 	}
 
-	private static JsonSchema parseSchema(String schema) {
+	private static JsonSchema parseSchema(McpJsonMapper jsonMapper, String schema) {
 		try {
-			return OBJECT_MAPPER.readValue(schema, JsonSchema.class);
+			return jsonMapper.readValue(schema, JsonSchema.class);
 		}
 		catch (IOException e) {
 			throw new IllegalArgumentException("Invalid schema: " + schema, e);
@@ -1425,17 +1377,17 @@ public record CallToolRequest( // @formatter:off
 		@JsonProperty("arguments") Map arguments,
 		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
-		public CallToolRequest(String name, String jsonArguments) {
-			this(name, parseJsonArguments(jsonArguments), null);
+		public CallToolRequest(McpJsonMapper jsonMapper, String name, String jsonArguments) {
+			this(name, parseJsonArguments(jsonMapper, jsonArguments), null);
 		}
 
 		public CallToolRequest(String name, Map arguments) {
 			this(name, arguments, null);
 		}
 
-		private static Map parseJsonArguments(String jsonArguments) {
+		private static Map parseJsonArguments(McpJsonMapper jsonMapper, String jsonArguments) {
 			try {
-				return OBJECT_MAPPER.readValue(jsonArguments, MAP_TYPE_REF);
+				return jsonMapper.readValue(jsonArguments, MAP_TYPE_REF);
 			}
 			catch (IOException e) {
 				throw new IllegalArgumentException("Invalid arguments: " + jsonArguments, e);
@@ -1464,8 +1416,8 @@ public Builder arguments(Map arguments) {
 				return this;
 			}
 
-			public Builder arguments(String jsonArguments) {
-				this.arguments = parseJsonArguments(jsonArguments);
+			public Builder arguments(McpJsonMapper jsonMapper, String jsonArguments) {
+				this.arguments = parseJsonArguments(jsonMapper, jsonArguments);
 				return this;
 			}
 
@@ -1576,10 +1528,10 @@ public Builder structuredContent(Object structuredContent) {
 				return this;
 			}
 
-			public Builder structuredContent(String structuredContent) {
+			public Builder structuredContent(McpJsonMapper jsonMapper, String structuredContent) {
 				Assert.hasText(structuredContent, "structuredContent must not be empty");
 				try {
-					this.structuredContent = OBJECT_MAPPER.readValue(structuredContent, MAP_TYPE_REF);
+					this.structuredContent = jsonMapper.readValue(structuredContent, MAP_TYPE_REF);
 				}
 				catch (IOException e) {
 					throw new IllegalArgumentException("Invalid structured content: " + structuredContent, e);
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index 747b45490..b9ff041a9 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -11,12 +11,12 @@
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.concurrent.atomic.AtomicReference;
 
-import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
 import io.modelcontextprotocol.server.McpInitRequestHandler;
 import io.modelcontextprotocol.server.McpNotificationHandler;
 import io.modelcontextprotocol.server.McpRequestHandler;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -153,7 +153,7 @@ public boolean isNotificationForLevelAllowed(McpSchema.LoggingLevel loggingLevel
 	}
 
 	@Override
-	public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+	public  Mono sendRequest(String method, Object requestParams, TypeRef typeRef) {
 		String requestId = this.generateRequestId();
 
 		return Mono.create(sink -> {
@@ -259,7 +259,7 @@ private Mono handleIncomingRequest(McpSchema.JSONRPCR
 			if (McpSchema.METHOD_INITIALIZE.equals(request.method())) {
 				// TODO handle situation where already initialized!
 				McpSchema.InitializeRequest initializeRequest = transport.unmarshalFrom(request.params(),
-						new TypeReference() {
+						new TypeRef() {
 						});
 
 				this.state.lazySet(STATE_INITIALIZING);
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
index 3473a4da8..767ed673e 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
@@ -4,7 +4,7 @@
 
 package io.modelcontextprotocol.spec;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 import reactor.core.publisher.Mono;
 
 /**
@@ -37,7 +37,7 @@ public interface McpSession {
 	 * @param typeRef the TypeReference describing the expected response type
 	 * @return a Mono that will emit the response when received
 	 */
-	 Mono sendRequest(String method, Object requestParams, TypeReference typeRef);
+	 Mono sendRequest(String method, Object requestParams, TypeRef typeRef);
 
 	/**
 	 * Sends a notification to the model client or server without parameters.
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
index 53b56c70f..ec03dd424 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -15,7 +15,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpAsyncServerExchange;
@@ -110,7 +110,7 @@ private String generateRequestId() {
 	}
 
 	@Override
-	public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+	public  Mono sendRequest(String method, Object requestParams, TypeRef typeRef) {
 		return Mono.defer(() -> {
 			McpLoggableSession listeningStream = this.listeningStreamRef.get();
 			return listeningStream.sendRequest(method, requestParams, typeRef);
@@ -347,7 +347,7 @@ public boolean isNotificationForLevelAllowed(McpSchema.LoggingLevel loggingLevel
 		}
 
 		@Override
-		public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+		public  Mono sendRequest(String method, Object requestParams, TypeRef typeRef) {
 			String requestId = McpStreamableServerSession.this.generateRequestId();
 
 			McpStreamableServerSession.this.requestIdToStream.put(requestId, this);
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
index 1922548a6..0a732bab6 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
@@ -6,8 +6,8 @@
 
 import java.util.List;
 
-import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
+import io.modelcontextprotocol.json.TypeRef;
 import reactor.core.publisher.Mono;
 
 /**
@@ -77,7 +77,7 @@ default void close() {
 	 * @param typeRef the type reference for the object to unmarshal
 	 * @return the unmarshalled object
 	 */
-	 T unmarshalFrom(Object data, TypeReference typeRef);
+	 T unmarshalFrom(Object data, TypeRef typeRef);
 
 	default List protocolVersions() {
 		return List.of(ProtocolVersions.MCP_2024_11_05);
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java b/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
index aa33a8167..0bf70d5b8 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
@@ -4,7 +4,7 @@
 
 package io.modelcontextprotocol.spec;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Mono;
 
@@ -31,7 +31,7 @@ public MissingMcpTransportSession(String sessionId) {
 	}
 
 	@Override
-	public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+	public  Mono sendRequest(String method, Object requestParams, TypeRef typeRef) {
 		return Mono.error(new IllegalStateException("Stream unavailable for session " + this.sessionId));
 	}
 
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java b/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
index 9d411cd41..6d53ed516 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
@@ -11,7 +11,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSession;
@@ -33,7 +33,7 @@ public class KeepAliveScheduler {
 
 	private static final Logger logger = LoggerFactory.getLogger(KeepAliveScheduler.class);
 
-	private static final TypeReference OBJECT_TYPE_REF = new TypeReference<>() {
+	private static final TypeRef OBJECT_TYPE_REF = new TypeRef<>() {
 	};
 
 	/** Initial delay before the first keepAlive call */
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java b/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
index b1113a6d0..9854de210 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
@@ -9,8 +9,8 @@
 import java.util.function.BiConsumer;
 import java.util.function.Function;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCNotification;
@@ -99,8 +99,8 @@ public Mono closeGracefully() {
 	}
 
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return new ObjectMapper().convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return McpJsonMapper.getDefault().convertValue(data, typeRef);
 	}
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java b/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
index 778746faa..f3d6b77a7 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
@@ -8,8 +8,8 @@
 import java.util.List;
 import java.util.function.BiConsumer;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCNotification;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCRequest;
@@ -67,8 +67,8 @@ public Mono closeGracefully() {
 	}
 
 	@Override
-	public  T unmarshalFrom(Object data, TypeReference typeRef) {
-		return new ObjectMapper().convertValue(data, typeRef);
+	public  T unmarshalFrom(Object data, TypeRef typeRef) {
+		return McpJsonMapper.getDefault().convertValue(data, typeRef);
 	}
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index af802df48..859dc5f82 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.client;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -22,8 +23,6 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
@@ -177,7 +176,12 @@ void testListAllToolsReturnsImmutableList() {
 				.consumeNextWith(result -> {
 					assertThat(result.tools()).isNotNull();
 					// Verify that the returned list is immutable
-					assertThatThrownBy(() -> result.tools().add(new Tool("test", "test", "{\"type\":\"object\"}")))
+					assertThatThrownBy(() -> result.tools()
+						.add(Tool.builder()
+							.name("test")
+							.title("test")
+							.inputSchema(JSON_MAPPER, "{\"type\":\"object\"}")
+							.build()))
 						.isInstanceOf(UnsupportedOperationException.class);
 				})
 				.verifyComplete();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 4f6551199..6ccf56d73 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -22,8 +22,6 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
index 89848c549..1e015ca5e 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
@@ -28,7 +28,6 @@ public class HttpClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncCl
 
 	@Override
 	protected McpClientTransport createMcpTransport() {
-
 		return HttpClientStreamableHttpTransport.builder(host).build();
 	}
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
index cab847512..612a65898 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
@@ -4,14 +4,13 @@
 
 package io.modelcontextprotocol.client;
 
+import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Function;
 
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.MockMcpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
@@ -24,6 +23,7 @@
 import reactor.core.publisher.Mono;
 
 import static io.modelcontextprotocol.spec.McpSchema.METHOD_INITIALIZE;
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
@@ -93,7 +93,7 @@ void testSuccessfulInitialization() {
 	}
 
 	@Test
-	void testToolsChangeNotificationHandling() throws JsonProcessingException {
+	void testToolsChangeNotificationHandling() throws IOException {
 		MockMcpClientTransport transport = initializationEnabledTransport();
 
 		// Create a list to store received tools for verification
@@ -110,8 +110,11 @@ void testToolsChangeNotificationHandling() throws JsonProcessingException {
 
 		// Create a mock tools list that the server will return
 		Map inputSchema = Map.of("type", "object", "properties", Map.of(), "required", List.of());
-		McpSchema.Tool mockTool = new McpSchema.Tool("test-tool-1", "Test Tool 1 Description",
-				new ObjectMapper().writeValueAsString(inputSchema));
+		McpSchema.Tool mockTool = McpSchema.Tool.builder()
+			.name("test-tool-1")
+			.description("Test Tool 1 Description")
+			.inputSchema(JSON_MAPPER, JSON_MAPPER.writeValueAsString(inputSchema))
+			.build();
 
 		// Create page 1 response with nextPageToken
 		String nextPageToken = "page2Token";
@@ -131,9 +134,11 @@ void testToolsChangeNotificationHandling() throws JsonProcessingException {
 		transport.simulateIncomingMessage(toolsListResponse1);
 
 		// Create mock tools for page 2
-		McpSchema.Tool mockTool2 = new McpSchema.Tool("test-tool-2", "Test Tool 2 Description",
-				new ObjectMapper().writeValueAsString(inputSchema));
-
+		McpSchema.Tool mockTool2 = McpSchema.Tool.builder()
+			.name("test-tool-2")
+			.description("Test Tool 2 Description")
+			.inputSchema(JSON_MAPPER, JSON_MAPPER.writeValueAsString(inputSchema))
+			.build();
 		// Create page 2 response with no nextPageToken (last page)
 		McpSchema.ListToolsResult mockToolsResult2 = new McpSchema.ListToolsResult(List.of(mockTool2), null);
 
@@ -321,7 +326,7 @@ void testSamplingCreateMessageRequestHandling() {
 		assertThat(response.error()).isNull();
 
 		McpSchema.CreateMessageResult result = transport.unmarshalFrom(response.result(),
-				new TypeReference() {
+				new TypeRef() {
 				});
 		assertThat(result).isNotNull();
 		assertThat(result.role()).isEqualTo(McpSchema.Role.ASSISTANT);
@@ -425,7 +430,7 @@ void testElicitationCreateRequestHandling() {
 		assertThat(response.id()).isEqualTo("test-id");
 		assertThat(response.error()).isNull();
 
-		McpSchema.ElicitResult result = transport.unmarshalFrom(response.result(), new TypeReference<>() {
+		McpSchema.ElicitResult result = transport.unmarshalFrom(response.result(), new TypeRef<>() {
 		});
 		assertThat(result).isNotNull();
 		assertThat(result.action()).isEqualTo(McpSchema.ElicitResult.Action.ACCEPT);
@@ -470,7 +475,7 @@ void testElicitationFailRequestHandling(McpSchema.ElicitResult.Action action) {
 		assertThat(response.id()).isEqualTo("test-id");
 		assertThat(response.error()).isNull();
 
-		McpSchema.ElicitResult result = transport.unmarshalFrom(response.result(), new TypeReference<>() {
+		McpSchema.ElicitResult result = transport.unmarshalFrom(response.result(), new TypeRef<>() {
 		});
 		assertThat(result).isNotNull();
 		assertThat(result.action()).isEqualTo(action);
@@ -551,4 +556,4 @@ void testPingMessageRequestHandling() {
 		asyncMcpClient.closeGracefully();
 	}
 
-}
\ No newline at end of file
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
index ae33898b7..3e29e89ab 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
@@ -4,8 +4,7 @@
 
 package io.modelcontextprotocol.client;
 
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.ProtocolVersions;
@@ -16,6 +15,7 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThatCode;
 
 class McpAsyncClientTests {
@@ -31,8 +31,6 @@ class McpAsyncClientTests {
 
 	private static final String CONTEXT_KEY = "context.key";
 
-	private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
-
 	@Test
 	void validateContextPassedToTransportConnect() {
 		McpClientTransport transport = new McpClientTransport() {
@@ -73,8 +71,13 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			}
 
 			@Override
-			public  T unmarshalFrom(Object data, TypeReference typeRef) {
-				return OBJECT_MAPPER.convertValue(data, typeRef);
+			public  T unmarshalFrom(Object data, TypeRef typeRef) {
+				return JSON_MAPPER.convertValue(data, new TypeRef<>() {
+					@Override
+					public java.lang.reflect.Type getType() {
+						return typeRef.getType();
+					}
+				});
 			}
 		};
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java b/mcp/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
new file mode 100644
index 000000000..63ec015fe
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
@@ -0,0 +1,19 @@
+package io.modelcontextprotocol.client;
+
+import io.modelcontextprotocol.client.transport.ServerParameters;
+
+public final class ServerParameterUtils {
+
+	private ServerParameterUtils() {
+	}
+
+	public static ServerParameters createServerParameters() {
+		if (System.getProperty("os.name").toLowerCase().contains("win")) {
+			return ServerParameters.builder("cmd.exe")
+				.args("/c", "npx.cmd", "-y", "@modelcontextprotocol/server-everything", "stdio")
+				.build();
+		}
+		return ServerParameters.builder("npx").args("-y", "@modelcontextprotocol/server-everything", "stdio").build();
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
index ef404c9ae..aa8aaa397 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
@@ -11,6 +11,9 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import org.junit.jupiter.api.Timeout;
 
+import static io.modelcontextprotocol.client.ServerParameterUtils.createServerParameters;
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
+
 /**
  * Tests for the {@link McpAsyncClient} with {@link StdioClientTransport}.
  *
@@ -29,18 +32,7 @@ class StdioMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
 	@Override
 	protected McpClientTransport createMcpTransport() {
-		ServerParameters stdioParams;
-		if (System.getProperty("os.name").toLowerCase().contains("win")) {
-			stdioParams = ServerParameters.builder("cmd.exe")
-				.args("/c", "npx.cmd", "-y", "@modelcontextprotocol/server-everything", "stdio")
-				.build();
-		}
-		else {
-			stdioParams = ServerParameters.builder("npx")
-				.args("-y", "@modelcontextprotocol/server-everything", "stdio")
-				.build();
-		}
-		return new StdioClientTransport(stdioParams);
+		return new StdioClientTransport(createServerParameters(), JSON_MAPPER);
 	}
 
 	protected Duration getInitializationTimeout() {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
index 95c1e2947..b1e567989 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
@@ -17,6 +17,8 @@
 import reactor.core.publisher.Sinks;
 import reactor.test.StepVerifier;
 
+import static io.modelcontextprotocol.client.ServerParameterUtils.createServerParameters;
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
@@ -37,18 +39,8 @@ class StdioMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
 	@Override
 	protected McpClientTransport createMcpTransport() {
-		ServerParameters stdioParams;
-		if (System.getProperty("os.name").toLowerCase().contains("win")) {
-			stdioParams = ServerParameters.builder("cmd.exe")
-				.args("/c", "npx.cmd", "-y", "@modelcontextprotocol/server-everything", "stdio")
-				.build();
-		}
-		else {
-			stdioParams = ServerParameters.builder("npx")
-				.args("-y", "@modelcontextprotocol/server-everything", "stdio")
-				.build();
-		}
-		return new StdioClientTransport(stdioParams);
+		ServerParameters stdioParams = createServerParameters();
+		return new StdioClientTransport(stdioParams, JSON_MAPPER);
 	}
 
 	@Test
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
index e088b8773..c5c365798 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
@@ -14,8 +14,6 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.common.McpTransportContext;
@@ -38,6 +36,7 @@
 import org.springframework.http.codec.ServerSentEvent;
 import org.springframework.web.util.UriComponentsBuilder;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.mockito.ArgumentMatchers.any;
@@ -78,8 +77,8 @@ static class TestHttpClientSseClientTransport extends HttpClientSseClientTranspo
 
 		public TestHttpClientSseClientTransport(final String baseUri) {
 			super(HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build(),
-					HttpRequest.newBuilder().header("Content-Type", "application/json"), baseUri, "/sse",
-					new ObjectMapper(), McpAsyncHttpClientRequestCustomizer.NOOP);
+					HttpRequest.newBuilder().header("Content-Type", "application/json"), baseUri, "/sse", JSON_MAPPER,
+					McpAsyncHttpClientRequestCustomizer.NOOP);
 		}
 
 		public int getInboundMessageCount() {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index 398b1540b..234874834 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -20,7 +20,6 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
-import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.atLeastOnce;
diff --git a/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
index fb19c62f7..8b2dea462 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
@@ -7,7 +7,6 @@
 import java.util.Map;
 import java.util.function.BiFunction;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpAsyncClient;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
@@ -100,19 +99,16 @@ public class AsyncServerMcpTransportContextIntegrationTests {
 
 	private final HttpServletStatelessServerTransport statelessServerTransport = HttpServletStatelessServerTransport
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final HttpServletStreamableServerTransportProvider streamableServerTransport = HttpServletStreamableServerTransportProvider
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final HttpServletSseServerTransportProvider sseServerTransport = HttpServletSseServerTransportProvider
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.messageEndpoint("/message")
 		.build();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
index 42747f717..cc8f4c4be 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.common;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.McpClient.SyncSpec;
 import io.modelcontextprotocol.client.McpSyncClient;
@@ -87,19 +86,16 @@ public class SyncServerMcpTransportContextIntegrationTests {
 
 	private final HttpServletStatelessServerTransport statelessServerTransport = HttpServletStatelessServerTransport
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final HttpServletStreamableServerTransportProvider streamableServerTransport = HttpServletStreamableServerTransportProvider
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.build();
 
 	private final HttpServletSseServerTransportProvider sseServerTransport = HttpServletSseServerTransportProvider
 		.builder()
-		.objectMapper(new ObjectMapper())
 		.contextExtractor(serverContextExtractor)
 		.messageEndpoint("/message")
 		.build();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index 0ba8bf929..93e49bc1c 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -92,18 +93,14 @@ void testImmediateClose() {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
 	@Test
 	@Deprecated
 	void testAddTool() {
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
@@ -117,7 +114,12 @@ void testAddTool() {
 
 	@Test
 	void testAddToolCall() {
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
+
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
@@ -133,7 +135,11 @@ void testAddToolCall() {
 	@Test
 	@Deprecated
 	void testAddDuplicateTool() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -153,7 +159,11 @@ void testAddDuplicateTool() {
 
 	@Test
 	void testAddDuplicateToolCall() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -173,8 +183,11 @@ void testAddDuplicateToolCall() {
 
 	@Test
 	void testDuplicateToolCallDuringBuilding() {
-		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
-				emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("duplicate-build-toolcall")
+			.title("Duplicate toolcall during building")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -186,7 +199,12 @@ void testDuplicateToolCallDuringBuilding() {
 
 	@Test
 	void testDuplicateToolsInBatchListRegistration() {
-		Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("batch-list-tool")
+			.title("Duplicate tool in batch list")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
+
 		List specs = List.of(
 				McpServerFeatures.AsyncToolSpecification.builder()
 					.tool(duplicateTool)
@@ -207,7 +225,11 @@ void testDuplicateToolsInBatchListRegistration() {
 
 	@Test
 	void testDuplicateToolsInBatchVarargsRegistration() {
-		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("batch-varargs-tool")
+			.title("Duplicate tool in batch varargs")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -226,7 +248,11 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 
 	@Test
 	void testRemoveTool() {
-		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool too = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -253,7 +279,11 @@ void testRemoveNonexistentTool() {
 
 	@Test
 	void testNotifyToolsListChanged() {
-		Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool too = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index 7503a2700..d54a5bd43 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -50,6 +50,7 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -102,7 +103,7 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 				return exchange.createMessage(mock(McpSchema.CreateMessageRequest.class))
 					.then(Mono.just(mock(CallToolResult.class)));
@@ -151,7 +152,7 @@ void testCreateMessageSuccess(String clientType) {
 		AtomicReference samplingResult = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
@@ -229,7 +230,7 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 		AtomicReference samplingResult = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
@@ -303,7 +304,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 				null);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var createMessageRequest = McpSchema.CreateMessageRequest.builder()
@@ -353,7 +354,7 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> exchange.createElicitation(mock(ElicitRequest.class))
 				.then(Mono.just(mock(CallToolResult.class))))
 			.build();
@@ -396,7 +397,7 @@ void testCreateElicitationSuccess(String clientType) {
 				null);
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var elicitationRequest = McpSchema.ElicitRequest.builder()
@@ -453,7 +454,7 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 		AtomicReference resultRef = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var elicitationRequest = McpSchema.ElicitRequest.builder()
@@ -524,7 +525,7 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 		AtomicReference resultRef = new AtomicReference<>();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				var elicitationRequest = ElicitRequest.builder()
@@ -622,7 +623,7 @@ void testRootsWithoutCapability(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		McpServerFeatures.SyncToolSpecification tool = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				exchange.listRoots(); // try to list roots
@@ -753,14 +754,6 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testToolCallSuccess(String clientType) {
@@ -770,7 +763,7 @@ void testToolCallSuccess(String clientType) {
 		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				try {
@@ -824,7 +817,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 				.tool(Tool.builder()
 					.name("tool1")
 					.description("tool1 description")
-					.inputSchema(emptyJsonSchema)
+					.inputSchema(EMPTY_JSON_SCHEMA)
 					.build())
 				.callHandler((exchange, request) -> {
 					// We trigger a timeout on blocking read, raising an exception
@@ -863,7 +856,7 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 		var expectedCallResponse = new McpSchema.CallToolResult(
 				List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=value")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 
 				McpTransportContext transportContext = exchange.transportContext();
@@ -915,7 +908,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 
 		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
-			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(emptyJsonSchema).build())
+			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
 				// perform a blocking call to a remote service
 				try {
@@ -984,7 +977,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 				.tool(Tool.builder()
 					.name("tool2")
 					.description("tool2 description")
-					.inputSchema(emptyJsonSchema)
+					.inputSchema(EMPTY_JSON_SCHEMA)
 					.build())
 				.callHandler((exchange, request) -> callResponse)
 				.build();
@@ -1036,7 +1029,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 			.tool(Tool.builder()
 				.name("logging-test")
 				.description("Test logging notifications")
-				.inputSchema(emptyJsonSchema)
+				.inputSchema(EMPTY_JSON_SCHEMA)
 				.build())
 			.callHandler((exchange, request) -> {
 
@@ -1150,7 +1143,7 @@ void testProgressNotification(String clientType) throws InterruptedException {
 			.tool(McpSchema.Tool.builder()
 				.name("progress-test")
 				.description("Test progress notifications")
-				.inputSchema(emptyJsonSchema)
+				.inputSchema(EMPTY_JSON_SCHEMA)
 				.build())
 			.callHandler((exchange, request) -> {
 
@@ -1263,7 +1256,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 							List.of(new PromptArgument("language", "Language", "string", false))),
 					(mcpSyncServerExchange, getPromptRequest) -> null))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.build()) {
@@ -1304,7 +1297,7 @@ void testPingSuccess(String clientType) {
 			.tool(Tool.builder()
 				.name("ping-async-test")
 				.description("Test ping async behavior")
-				.inputSchema(emptyJsonSchema)
+				.inputSchema(EMPTY_JSON_SCHEMA)
 				.build())
 			.callHandler((exchange, request) -> {
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 67579ce72..dae2e38f9 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -101,14 +102,6 @@ void testGetAsyncServer() {
 	// Tools Tests
 	// ---------------------------------------
 
-	String emptyJsonSchema = """
-			{
-				"$schema": "http://json-schema.org/draft-07/schema#",
-				"type": "object",
-				"properties": {}
-			}
-			""";
-
 	@Test
 	@Deprecated
 	void testAddTool() {
@@ -116,7 +109,11 @@ void testAddTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(newTool,
 				(exchange, args) -> new CallToolResult(List.of(), false))))
 			.doesNotThrowAnyException();
@@ -130,7 +127,12 @@ void testAddToolCall() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		Tool newTool = new McpSchema.Tool("new-tool", "New test tool", emptyJsonSchema);
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
+
 		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(newTool)
 			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
@@ -142,7 +144,11 @@ void testAddToolCall() {
 	@Test
 	@Deprecated
 	void testAddDuplicateTool() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -159,7 +165,11 @@ void testAddDuplicateTool() {
 
 	@Test
 	void testAddDuplicateToolCall() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Duplicate tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -177,8 +187,11 @@ void testAddDuplicateToolCall() {
 
 	@Test
 	void testDuplicateToolCallDuringBuilding() {
-		Tool duplicateTool = new Tool("duplicate-build-toolcall", "Duplicate toolcall during building",
-				emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("duplicate-build-toolcall")
+			.title("Duplicate toolcall during building")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -190,7 +203,11 @@ void testDuplicateToolCallDuringBuilding() {
 
 	@Test
 	void testDuplicateToolsInBatchListRegistration() {
-		Tool duplicateTool = new Tool("batch-list-tool", "Duplicate tool in batch list", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("batch-list-tool")
+			.title("Duplicate tool in batch list")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		List specs = List.of(
 				McpServerFeatures.SyncToolSpecification.builder()
 					.tool(duplicateTool)
@@ -211,7 +228,11 @@ void testDuplicateToolsInBatchListRegistration() {
 
 	@Test
 	void testDuplicateToolsInBatchVarargsRegistration() {
-		Tool duplicateTool = new Tool("batch-varargs-tool", "Duplicate tool in batch varargs", emptyJsonSchema);
+		Tool duplicateTool = McpSchema.Tool.builder()
+			.name("batch-varargs-tool")
+			.title("Duplicate tool in batch varargs")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -230,7 +251,11 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 
 	@Test
 	void testRemoveTool() {
-		Tool tool = new McpSchema.Tool(TEST_TOOL_NAME, "Test tool", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -429,7 +454,6 @@ void testRootsChangeHandlers() {
 				}
 			}))
 			.build();
-
 		assertThat(singleConsumerServer).isNotNull();
 		assertThatCode(() -> singleConsumerServer.closeGracefully()).doesNotThrowAnyException();
 		onClose();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java b/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
index 6744826c9..8fe8e6fb0 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
@@ -4,12 +4,14 @@
 
 package io.modelcontextprotocol.server;
 
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 import java.util.List;
 import java.util.Map;
 
+import io.modelcontextprotocol.spec.McpSchema;
 import org.junit.jupiter.api.Test;
 
 import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
@@ -26,16 +28,14 @@
  */
 class AsyncToolSpecificationBuilderTest {
 
-	String emptyJsonSchema = """
-			{
-				"type": "object"
-			}
-			""";
-
 	@Test
 	void builderShouldCreateValidAsyncToolSpecification() {
 
-		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name("test-tool")
+			.title("A test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		McpServerFeatures.AsyncToolSpecification specification = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(tool)
@@ -58,7 +58,11 @@ void builderShouldThrowExceptionWhenToolIsNull() {
 
 	@Test
 	void builderShouldThrowExceptionWhenCallToolIsNull() {
-		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name("test-tool")
+			.title("A test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		assertThatThrownBy(() -> McpServerFeatures.AsyncToolSpecification.builder().tool(tool).build())
 			.isInstanceOf(IllegalArgumentException.class)
@@ -67,7 +71,11 @@ void builderShouldThrowExceptionWhenCallToolIsNull() {
 
 	@Test
 	void builderShouldAllowMethodChaining() {
-		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name("test-tool")
+			.title("A test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		McpServerFeatures.AsyncToolSpecification.Builder builder = McpServerFeatures.AsyncToolSpecification.builder();
 
 		// Then - verify method chaining returns the same builder instance
@@ -78,7 +86,11 @@ void builderShouldAllowMethodChaining() {
 
 	@Test
 	void builtSpecificationShouldExecuteCallToolCorrectly() {
-		Tool tool = new Tool("calculator", "Simple calculator", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name("calculator")
+			.title("Simple calculator")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		String expectedResult = "42";
 
 		McpServerFeatures.AsyncToolSpecification specification = McpServerFeatures.AsyncToolSpecification.builder()
@@ -103,7 +115,11 @@ void builtSpecificationShouldExecuteCallToolCorrectly() {
 	@Test
 	@SuppressWarnings("deprecation")
 	void deprecatedConstructorShouldWorkCorrectly() {
-		Tool tool = new Tool("deprecated-tool", "A deprecated tool", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name("deprecated-tool")
+			.title("A deprecated tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		String expectedResult = "deprecated result";
 
 		// Test the deprecated constructor that takes a 'call' function
@@ -143,7 +159,11 @@ void deprecatedConstructorShouldWorkCorrectly() {
 
 	@Test
 	void fromSyncShouldConvertSyncToolSpecificationCorrectly() {
-		Tool tool = new Tool("sync-tool", "A sync tool", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name("sync-tool")
+			.title("A sync tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		String expectedResult = "sync result";
 
 		// Create a sync tool specification
@@ -178,7 +198,11 @@ void fromSyncShouldConvertSyncToolSpecificationCorrectly() {
 	@Test
 	@SuppressWarnings("deprecation")
 	void fromSyncShouldConvertSyncToolSpecificationWithDeprecatedCallCorrectly() {
-		Tool tool = new Tool("sync-deprecated-tool", "A sync tool with deprecated call", emptyJsonSchema);
+		Tool tool = McpSchema.Tool.builder()
+			.name("sync-deprecated-tool")
+			.title("A sync tool with deprecated call")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		String expectedResult = "sync deprecated result";
 		McpAsyncServerExchange nullExchange = null; // Mock or create a suitable exchange
 													// if needed
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
index 8e618b9a8..fd05b593b 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
@@ -7,7 +7,6 @@
 import java.time.Duration;
 import java.util.Map;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.common.McpTransportContext;
@@ -42,7 +41,6 @@ class HttpServletSseIntegrationTests extends AbstractMcpClientServerIntegrationT
 	public void before() {
 		// Create and configure the transport provider
 		mcpServerTransportProvider = HttpServletSseServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
 			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index 732b2ba06..b40f90e08 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -11,7 +11,6 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.BiFunction;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.common.McpTransportContext;
@@ -48,6 +47,8 @@
 
 import static io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport.APPLICATION_JSON;
 import static io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport.TEXT_EVENT_STREAM;
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -69,7 +70,6 @@ class HttpServletStatelessIntegrationTests {
 	@BeforeEach
 	public void before() {
 		this.mcpStatelessServerTransport = HttpServletStatelessServerTransport.builder()
-			.objectMapper(new ObjectMapper())
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.build();
 
@@ -108,15 +108,6 @@ public void after() {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
-
-	String emptyJsonSchema = """
-			{
-			"$schema": "http://json-schema.org/draft-07/schema#",
-			"type": "object",
-			"properties": {}
-			}
-			""";
-
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "httpclient" })
 	void testToolCallSuccess(String clientType) {
@@ -125,7 +116,8 @@ void testToolCallSuccess(String clientType) {
 
 		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
 		McpStatelessServerFeatures.SyncToolSpecification tool1 = new McpStatelessServerFeatures.SyncToolSpecification(
-				new Tool("tool1", "tool1 description", emptyJsonSchema), (transportContext, request) -> {
+				Tool.builder().name("tool1").title("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build(),
+				(transportContext, request) -> {
 					// perform a blocking call to a remote service
 					String response = RestClient.create()
 						.get()
@@ -621,7 +613,7 @@ void testThrownMcpErrorAndJsonRpcError() throws Exception {
 		MockHttpServletRequest request = new MockHttpServletRequest("POST", CUSTOM_MESSAGE_ENDPOINT);
 		MockHttpServletResponse response = new MockHttpServletResponse();
 
-		byte[] content = new ObjectMapper().writeValueAsBytes(jsonrpcRequest);
+		byte[] content = JSON_MAPPER.writeValueAsBytes(jsonrpcRequest);
 		request.setContent(content);
 		request.addHeader("Content-Type", "application/json");
 		request.addHeader("Content-Length", Integer.toString(content.length));
@@ -633,7 +625,7 @@ void testThrownMcpErrorAndJsonRpcError() throws Exception {
 
 		mcpStatelessServerTransport.service(request, response);
 
-		McpSchema.JSONRPCResponse jsonrpcResponse = new ObjectMapper().readValue(response.getContentAsByteArray(),
+		McpSchema.JSONRPCResponse jsonrpcResponse = JSON_MAPPER.readValue(response.getContentAsByteArray(),
 				McpSchema.JSONRPCResponse.class);
 
 		assertThat(jsonrpcResponse).isNotNull();
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
index 327ec1b21..96f1524b7 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
@@ -6,8 +6,6 @@
 
 import org.junit.jupiter.api.Timeout;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 
@@ -21,10 +19,7 @@
 class HttpServletStreamableAsyncServerTests extends AbstractMcpAsyncServerTests {
 
 	protected McpStreamableServerTransportProvider createMcpTransportProvider() {
-		return HttpServletStreamableServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
-			.mcpEndpoint("/mcp/message")
-			.build();
+		return HttpServletStreamableServerTransportProvider.builder().mcpEndpoint("/mcp/message").build();
 	}
 
 	@Override
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 1f6a1fe58..223c78a94 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -7,7 +7,6 @@
 import java.time.Duration;
 import java.util.Map;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
 import io.modelcontextprotocol.common.McpTransportContext;
@@ -40,7 +39,6 @@ class HttpServletStreamableIntegrationTests extends AbstractMcpClientServerInteg
 	public void before() {
 		// Create and configure the transport provider
 		mcpServerTransportProvider = HttpServletStreamableServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
 			.contextExtractor(TEST_CONTEXT_EXTRACTOR)
 			.mcpEndpoint(MESSAGE_ENDPOINT)
 			.keepAliveInterval(Duration.ofSeconds(1))
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
index 66fa2b2ac..87c0712dc 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
@@ -6,8 +6,6 @@
 
 import org.junit.jupiter.api.Timeout;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 
@@ -21,10 +19,7 @@
 class HttpServletStreamableSyncServerTests extends AbstractMcpSyncServerTests {
 
 	protected McpStreamableServerTransportProvider createMcpTransportProvider() {
-		return HttpServletStreamableServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
-			.mcpEndpoint("/mcp/message")
-			.build();
+		return HttpServletStreamableServerTransportProvider.builder().mcpEndpoint("/mcp/message").build();
 	}
 
 	@Override
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
index 104349116..640d34c9c 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
@@ -10,10 +10,10 @@
 import java.util.List;
 import java.util.Map;
 
-import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpServerSession;
+import io.modelcontextprotocol.json.TypeRef;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.mockito.Mock;
@@ -66,7 +66,7 @@ void testListRootsWithSinglePage() {
 		McpSchema.ListRootsResult singlePageResult = new McpSchema.ListRootsResult(roots, null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), any(McpSchema.PaginatedRequest.class),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(singlePageResult));
 
 		StepVerifier.create(exchange.listRoots()).assertNext(result -> {
@@ -94,11 +94,11 @@ void testListRootsWithMultiplePages() {
 		McpSchema.ListRootsResult page2Result = new McpSchema.ListRootsResult(page2Roots, null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest(null)),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page1Result));
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest("cursor1")),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page2Result));
 
 		StepVerifier.create(exchange.listRoots()).assertNext(result -> {
@@ -120,7 +120,7 @@ void testListRootsWithEmptyResult() {
 		McpSchema.ListRootsResult emptyResult = new McpSchema.ListRootsResult(new ArrayList<>(), null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), any(McpSchema.PaginatedRequest.class),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(emptyResult));
 
 		StepVerifier.create(exchange.listRoots()).assertNext(result -> {
@@ -140,7 +140,7 @@ void testListRootsWithSpecificCursor() {
 		McpSchema.ListRootsResult result = new McpSchema.ListRootsResult(roots, "nextCursor");
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest("someCursor")),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(result));
 
 		StepVerifier.create(exchange.listRoots("someCursor")).assertNext(listResult -> {
@@ -154,7 +154,7 @@ void testListRootsWithSpecificCursor() {
 	void testListRootsWithError() {
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), any(McpSchema.PaginatedRequest.class),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.error(new RuntimeException("Network error")));
 
 		// When & Then
@@ -175,11 +175,11 @@ void testListRootsUnmodifiabilityAfterAccumulation() {
 		McpSchema.ListRootsResult page2Result = new McpSchema.ListRootsResult(page2Roots, null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest(null)),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page1Result));
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest("cursor1")),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page2Result));
 
 		StepVerifier.create(exchange.listRoots()).assertNext(result -> {
@@ -314,8 +314,7 @@ void testCreateElicitationWithNullCapabilities() {
 			});
 
 		// Verify that sendRequest was never called due to null capabilities
-		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(),
-				any(TypeReference.class));
+		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(), any(TypeRef.class));
 	}
 
 	@Test
@@ -339,8 +338,7 @@ void testCreateElicitationWithoutElicitationCapabilities() {
 
 		// Verify that sendRequest was never called due to missing elicitation
 		// capabilities
-		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(),
-				any(TypeReference.class));
+		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(), any(TypeRef.class));
 	}
 
 	@Test
@@ -374,8 +372,7 @@ void testCreateElicitationWithComplexRequest() {
 			.content(responseContent)
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		StepVerifier.create(exchangeWithElicitation.createElicitation(elicitRequest)).assertNext(result -> {
@@ -405,8 +402,7 @@ void testCreateElicitationWithDeclineAction() {
 			.message(McpSchema.ElicitResult.Action.DECLINE)
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		StepVerifier.create(exchangeWithElicitation.createElicitation(elicitRequest)).assertNext(result -> {
@@ -433,8 +429,7 @@ void testCreateElicitationWithCancelAction() {
 			.message(McpSchema.ElicitResult.Action.CANCEL)
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		StepVerifier.create(exchangeWithElicitation.createElicitation(elicitRequest)).assertNext(result -> {
@@ -457,8 +452,7 @@ void testCreateElicitationWithSessionError() {
 			.message("Please provide your name")
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.error(new RuntimeException("Session communication error")));
 
 		StepVerifier.create(exchangeWithElicitation.createElicitation(elicitRequest)).verifyErrorSatisfies(error -> {
@@ -488,7 +482,7 @@ void testCreateMessageWithNullCapabilities() {
 
 		// Verify that sendRequest was never called due to null capabilities
 		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), any(),
-				any(TypeReference.class));
+				any(TypeRef.class));
 	}
 
 	@Test
@@ -513,7 +507,7 @@ void testCreateMessageWithoutSamplingCapabilities() {
 
 		// Verify that sendRequest was never called due to missing sampling capabilities
 		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), any(),
-				any(TypeReference.class));
+				any(TypeRef.class));
 	}
 
 	@Test
@@ -539,7 +533,7 @@ void testCreateMessageWithBasicRequest() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		StepVerifier.create(exchangeWithSampling.createMessage(createMessageRequest)).assertNext(result -> {
@@ -577,7 +571,7 @@ void testCreateMessageWithImageContent() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		StepVerifier.create(exchangeWithSampling.createMessage(createMessageRequest)).assertNext(result -> {
@@ -603,7 +597,7 @@ void testCreateMessageWithSessionError() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.error(new RuntimeException("Session communication error")));
 
 		StepVerifier.create(exchangeWithSampling.createMessage(createMessageRequest)).verifyErrorSatisfies(error -> {
@@ -635,7 +629,7 @@ void testCreateMessageWithIncludeContext() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		StepVerifier.create(exchangeWithSampling.createMessage(createMessageRequest)).assertNext(result -> {
@@ -653,7 +647,7 @@ void testPingWithSuccessfulResponse() {
 
 		java.util.Map expectedResponse = java.util.Map.of();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResponse));
 
 		StepVerifier.create(exchange.ping()).assertNext(result -> {
@@ -662,14 +656,14 @@ void testPingWithSuccessfulResponse() {
 		}).verifyComplete();
 
 		// Verify that sendRequest was called with correct parameters
-		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class));
+		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class));
 	}
 
 	@Test
 	void testPingWithMcpError() {
 		// Given - Mock an MCP-specific error during ping
 		McpError mcpError = new McpError("Server unavailable");
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class)))
 			.thenReturn(Mono.error(mcpError));
 
 		// When & Then
@@ -677,13 +671,13 @@ void testPingWithMcpError() {
 			assertThat(error).isInstanceOf(McpError.class).hasMessage("Server unavailable");
 		});
 
-		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class));
+		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class));
 	}
 
 	@Test
 	void testPingMultipleCalls() {
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class)))
 			.thenReturn(Mono.just(Map.of()))
 			.thenReturn(Mono.just(Map.of()));
 
@@ -698,7 +692,7 @@ void testPingMultipleCalls() {
 		}).verifyComplete();
 
 		// Verify that sendRequest was called twice
-		verify(mockSession, times(2)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class));
+		verify(mockSession, times(2)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class));
 	}
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
index f915895be..194c37000 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
@@ -12,14 +12,13 @@
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
 import org.apache.catalina.startup.Tomcat;
+
 import static org.assertj.core.api.Assertions.assertThat;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.server.transport.HttpServletSseServerTransportProvider;
@@ -59,7 +58,6 @@ class McpCompletionTests {
 	public void before() {
 		// Create and con figure the transport provider
 		mcpServerTransportProvider = HttpServletSseServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.build();
 
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
index a73ec7209..069d0f896 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
@@ -9,10 +9,10 @@
 import java.util.List;
 import java.util.Map;
 
-import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpServerSession;
+import io.modelcontextprotocol.json.TypeRef;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.mockito.Mock;
@@ -66,7 +66,7 @@ void testListRootsWithSinglePage() {
 		McpSchema.ListRootsResult singlePageResult = new McpSchema.ListRootsResult(roots, null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), any(McpSchema.PaginatedRequest.class),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(singlePageResult));
 
 		McpSchema.ListRootsResult result = exchange.listRoots();
@@ -94,11 +94,11 @@ void testListRootsWithMultiplePages() {
 		McpSchema.ListRootsResult page2Result = new McpSchema.ListRootsResult(page2Roots, null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest(null)),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page1Result));
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest("cursor1")),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page2Result));
 
 		McpSchema.ListRootsResult result = exchange.listRoots();
@@ -120,7 +120,7 @@ void testListRootsWithEmptyResult() {
 		McpSchema.ListRootsResult emptyResult = new McpSchema.ListRootsResult(new ArrayList<>(), null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), any(McpSchema.PaginatedRequest.class),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(emptyResult));
 
 		McpSchema.ListRootsResult result = exchange.listRoots();
@@ -140,7 +140,7 @@ void testListRootsWithSpecificCursor() {
 		McpSchema.ListRootsResult result = new McpSchema.ListRootsResult(roots, "nextCursor");
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest("someCursor")),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(result));
 
 		McpSchema.ListRootsResult listResult = exchange.listRoots("someCursor");
@@ -154,7 +154,7 @@ void testListRootsWithSpecificCursor() {
 	void testListRootsWithError() {
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), any(McpSchema.PaginatedRequest.class),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.error(new RuntimeException("Network error")));
 
 		// When & Then
@@ -173,11 +173,11 @@ void testListRootsUnmodifiabilityAfterAccumulation() {
 		McpSchema.ListRootsResult page2Result = new McpSchema.ListRootsResult(page2Roots, null);
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest(null)),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page1Result));
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_ROOTS_LIST), eq(new McpSchema.PaginatedRequest("cursor1")),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(page2Result));
 
 		McpSchema.ListRootsResult result = exchange.listRoots();
@@ -308,8 +308,7 @@ void testCreateElicitationWithNullCapabilities() {
 			.hasMessage("Client must be initialized. Call the initialize method first!");
 
 		// Verify that sendRequest was never called due to null capabilities
-		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(),
-				any(TypeReference.class));
+		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(), any(TypeRef.class));
 	}
 
 	@Test
@@ -333,8 +332,7 @@ void testCreateElicitationWithoutElicitationCapabilities() {
 
 		// Verify that sendRequest was never called due to missing elicitation
 		// capabilities
-		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(),
-				any(TypeReference.class));
+		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), any(), any(TypeRef.class));
 	}
 
 	@Test
@@ -369,8 +367,7 @@ void testCreateElicitationWithComplexRequest() {
 			.content(responseContent)
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		McpSchema.ElicitResult result = exchangeWithElicitation.createElicitation(elicitRequest);
@@ -401,8 +398,7 @@ void testCreateElicitationWithDeclineAction() {
 			.message(McpSchema.ElicitResult.Action.DECLINE)
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		McpSchema.ElicitResult result = exchangeWithElicitation.createElicitation(elicitRequest);
@@ -430,8 +426,7 @@ void testCreateElicitationWithCancelAction() {
 			.message(McpSchema.ElicitResult.Action.CANCEL)
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		McpSchema.ElicitResult result = exchangeWithElicitation.createElicitation(elicitRequest);
@@ -455,8 +450,7 @@ void testCreateElicitationWithSessionError() {
 			.message("Please provide your name")
 			.build();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest),
-				any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_ELICITATION_CREATE), eq(elicitRequest), any(TypeRef.class)))
 			.thenReturn(Mono.error(new RuntimeException("Session communication error")));
 
 		assertThatThrownBy(() -> exchangeWithElicitation.createElicitation(elicitRequest))
@@ -487,7 +481,7 @@ void testCreateMessageWithNullCapabilities() {
 
 		// Verify that sendRequest was never called due to null capabilities
 		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), any(),
-				any(TypeReference.class));
+				any(TypeRef.class));
 	}
 
 	@Test
@@ -512,7 +506,7 @@ void testCreateMessageWithoutSamplingCapabilities() {
 
 		// Verify that sendRequest was never called due to missing sampling capabilities
 		verify(mockSession, never()).sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), any(),
-				any(TypeReference.class));
+				any(TypeRef.class));
 	}
 
 	@Test
@@ -539,7 +533,7 @@ void testCreateMessageWithBasicRequest() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		McpSchema.CreateMessageResult result = exchangeWithSampling.createMessage(createMessageRequest);
@@ -578,7 +572,7 @@ void testCreateMessageWithImageContent() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		McpSchema.CreateMessageResult result = exchangeWithSampling.createMessage(createMessageRequest);
@@ -605,7 +599,7 @@ void testCreateMessageWithSessionError() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.error(new RuntimeException("Session communication error")));
 
 		assertThatThrownBy(() -> exchangeWithSampling.createMessage(createMessageRequest))
@@ -638,7 +632,7 @@ void testCreateMessageWithIncludeContext() {
 			.build();
 
 		when(mockSession.sendRequest(eq(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE), eq(createMessageRequest),
-				any(TypeReference.class)))
+				any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResult));
 
 		McpSchema.CreateMessageResult result = exchangeWithSampling.createMessage(createMessageRequest);
@@ -656,32 +650,32 @@ void testPingWithSuccessfulResponse() {
 
 		java.util.Map expectedResponse = java.util.Map.of();
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class)))
 			.thenReturn(Mono.just(expectedResponse));
 
 		exchange.ping();
 
 		// Verify that sendRequest was called with correct parameters
-		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class));
+		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class));
 	}
 
 	@Test
 	void testPingWithMcpError() {
 		// Given - Mock an MCP-specific error during ping
 		McpError mcpError = new McpError("Server unavailable");
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class)))
 			.thenReturn(Mono.error(mcpError));
 
 		// When & Then
 		assertThatThrownBy(() -> exchange.ping()).isInstanceOf(McpError.class).hasMessage("Server unavailable");
 
-		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class));
+		verify(mockSession, times(1)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class));
 	}
 
 	@Test
 	void testPingMultipleCalls() {
 
-		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class)))
+		when(mockSession.sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class)))
 			.thenReturn(Mono.just(Map.of()))
 			.thenReturn(Mono.just(Map.of()));
 
@@ -692,7 +686,7 @@ void testPingMultipleCalls() {
 		exchange.ping();
 
 		// Verify that sendRequest was called twice
-		verify(mockSession, times(2)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeReference.class));
+		verify(mockSession, times(2)).sendRequest(eq(McpSchema.METHOD_PING), eq(null), any(TypeRef.class));
 	}
 
 }
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
index 97db5fa06..b2dfbea25 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
@@ -8,6 +8,8 @@
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
+
 /**
  * Tests for {@link McpAsyncServer} using {@link StdioServerTransport}.
  *
@@ -17,7 +19,7 @@
 class StdioMcpAsyncServerTests extends AbstractMcpAsyncServerTests {
 
 	protected McpServerTransportProvider createMcpTransportProvider() {
-		return new StdioServerTransportProvider();
+		return new StdioServerTransportProvider(JSON_MAPPER);
 	}
 
 	@Override
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
index 1e01962e9..c97c75d38 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
@@ -8,6 +8,8 @@
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import org.junit.jupiter.api.Timeout;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
+
 /**
  * Tests for {@link McpSyncServer} using {@link StdioServerTransportProvider}.
  *
@@ -17,7 +19,7 @@
 class StdioMcpSyncServerTests extends AbstractMcpSyncServerTests {
 
 	protected McpServerTransportProvider createMcpTransportProvider() {
-		return new StdioServerTransportProvider();
+		return new StdioServerTransportProvider(JSON_MAPPER);
 	}
 
 	@Override
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java b/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
index 4aac46952..cd643c600 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
@@ -24,16 +25,10 @@
  */
 class SyncToolSpecificationBuilderTest {
 
-	String emptyJsonSchema = """
-			{
-				"type": "object"
-			}
-			""";
-
 	@Test
 	void builderShouldCreateValidSyncToolSpecification() {
 
-		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		Tool tool = Tool.builder().name("test-tool").title("A test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 
 		McpServerFeatures.SyncToolSpecification specification = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(tool)
@@ -55,7 +50,7 @@ void builderShouldThrowExceptionWhenToolIsNull() {
 
 	@Test
 	void builderShouldThrowExceptionWhenCallToolIsNull() {
-		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		Tool tool = Tool.builder().name("test-tool").description("A test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 
 		assertThatThrownBy(() -> McpServerFeatures.SyncToolSpecification.builder().tool(tool).build())
 			.isInstanceOf(IllegalArgumentException.class)
@@ -64,7 +59,7 @@ void builderShouldThrowExceptionWhenCallToolIsNull() {
 
 	@Test
 	void builderShouldAllowMethodChaining() {
-		Tool tool = new Tool("test-tool", "A test tool", emptyJsonSchema);
+		Tool tool = Tool.builder().name("test-tool").description("A test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
 		McpServerFeatures.SyncToolSpecification.Builder builder = McpServerFeatures.SyncToolSpecification.builder();
 
 		// Then - verify method chaining returns the same builder instance
@@ -74,7 +69,11 @@ void builderShouldAllowMethodChaining() {
 
 	@Test
 	void builtSpecificationShouldExecuteCallToolCorrectly() {
-		Tool tool = new Tool("calculator", "Simple calculator", emptyJsonSchema);
+		Tool tool = Tool.builder()
+			.name("calculator")
+			.description("Simple calculator")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		String expectedResult = "42";
 
 		McpServerFeatures.SyncToolSpecification specification = McpServerFeatures.SyncToolSpecification.builder()
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
index 0462cbafe..be88097b3 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
@@ -4,8 +4,6 @@
 
 package io.modelcontextprotocol.server.transport;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
 import io.modelcontextprotocol.server.McpServer;
@@ -40,7 +38,6 @@ public void before() {
 
 		// Create and configure the transport provider
 		mcpServerTransportProvider = HttpServletSseServerTransportProvider.builder()
-			.objectMapper(new ObjectMapper())
 			.baseUrl(CUSTOM_CONTEXT_PATH)
 			.messageEndpoint(CUSTOM_MESSAGE_ENDPOINT)
 			.sseEndpoint(CUSTOM_SSE_ENDPOINT)
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java b/mcp/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java
index 14987b5ac..6a70af33d 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java
@@ -14,7 +14,6 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpServerSession;
@@ -26,6 +25,7 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
@@ -50,8 +50,6 @@ class StdioServerTransportProviderTests {
 
 	private StdioServerTransportProvider transportProvider;
 
-	private ObjectMapper objectMapper;
-
 	private McpServerSession.Factory sessionFactory;
 
 	private McpServerSession mockSession;
@@ -64,8 +62,6 @@ void setUp() {
 		System.setOut(testOutPrintStream);
 		System.setErr(testOutPrintStream);
 
-		objectMapper = new ObjectMapper();
-
 		// Create mocks for session factory and session
 		mockSession = mock(McpServerSession.class);
 		sessionFactory = mock(McpServerSession.Factory.class);
@@ -75,7 +71,7 @@ void setUp() {
 		when(mockSession.closeGracefully()).thenReturn(Mono.empty());
 		when(mockSession.sendNotification(any(), any())).thenReturn(Mono.empty());
 
-		transportProvider = new StdioServerTransportProvider(objectMapper, System.in, testOutPrintStream);
+		transportProvider = new StdioServerTransportProvider(JSON_MAPPER, System.in, testOutPrintStream);
 	}
 
 	@AfterEach
@@ -105,7 +101,7 @@ void shouldHandleIncomingMessages() throws Exception {
 		String jsonMessage = "{\"jsonrpc\":\"2.0\",\"method\":\"test\",\"params\":{},\"id\":1}\n";
 		InputStream stream = new ByteArrayInputStream(jsonMessage.getBytes(StandardCharsets.UTF_8));
 
-		transportProvider = new StdioServerTransportProvider(objectMapper, stream, System.out);
+		transportProvider = new StdioServerTransportProvider(JSON_MAPPER, stream, System.out);
 		// Set up a real session to capture the message
 		AtomicReference capturedMessage = new AtomicReference<>();
 		CountDownLatch messageLatch = new CountDownLatch(1);
@@ -185,7 +181,7 @@ void shouldHandleMultipleCloseGracefullyCalls() {
 	@Test
 	void shouldHandleNotificationBeforeSessionFactoryIsSet() {
 
-		transportProvider = new StdioServerTransportProvider(objectMapper);
+		transportProvider = new StdioServerTransportProvider(JSON_MAPPER);
 		// Send notification before setting session factory
 		StepVerifier.create(transportProvider.notifyClients("testNotification", Map.of("key", "value")))
 			.verifyErrorSatisfies(error -> {
@@ -200,7 +196,7 @@ void shouldHandleInvalidJsonMessage() throws Exception {
 		String jsonMessage = "{invalid json}\n";
 		InputStream stream = new ByteArrayInputStream(jsonMessage.getBytes(StandardCharsets.UTF_8));
 
-		transportProvider = new StdioServerTransportProvider(objectMapper, stream, testOutPrintStream);
+		transportProvider = new StdioServerTransportProvider(JSON_MAPPER, stream, testOutPrintStream);
 
 		// Set up a session factory
 		transportProvider.setSessionFactory(sessionFactory);
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
index 30158543d..76ca29684 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
@@ -16,6 +16,7 @@
 import java.util.Map;
 import java.util.stream.Stream;
 
+import io.modelcontextprotocol.json.schema.jackson.DefaultJsonSchemaValidator;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
@@ -27,7 +28,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
-import io.modelcontextprotocol.spec.JsonSchemaValidator.ValidationResponse;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator.ValidationResponse;
 
 /**
  * Tests for {@link DefaultJsonSchemaValidator}.
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
index 85dcd26c2..86912b4bf 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
@@ -7,8 +7,8 @@
 import java.time.Duration;
 import java.util.Map;
 
-import com.fasterxml.jackson.core.type.TypeReference;
 import io.modelcontextprotocol.MockMcpClientTransport;
+import io.modelcontextprotocol.json.TypeRef;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -68,7 +68,7 @@ void testConstructorWithInvalidArguments() {
 			.hasMessageContaining("transport can not be null");
 	}
 
-	TypeReference responseType = new TypeReference<>() {
+	TypeRef responseType = new TypeRef<>() {
 	};
 
 	@Test
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index 81552100f..0926eebae 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.spec;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -17,7 +18,6 @@
 
 import org.junit.jupiter.api.Test;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.exc.InvalidTypeIdException;
 
 import io.modelcontextprotocol.spec.McpSchema.TextResourceContents;
@@ -29,14 +29,12 @@
  */
 public class McpSchemaTests {
 
-	ObjectMapper mapper = new ObjectMapper();
-
 	// Content Types Tests
 
 	@Test
 	void testTextContent() throws Exception {
 		McpSchema.TextContent test = new McpSchema.TextContent("XXX");
-		String value = mapper.writeValueAsString(test);
+		String value = JSON_MAPPER.writeValueAsString(test);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -47,7 +45,7 @@ void testTextContent() throws Exception {
 
 	@Test
 	void testTextContentDeserialization() throws Exception {
-		McpSchema.TextContent textContent = mapper.readValue("""
+		McpSchema.TextContent textContent = JSON_MAPPER.readValue("""
 				{"type":"text","text":"XXX","_meta":{"metaKey":"metaValue"}}""", McpSchema.TextContent.class);
 
 		assertThat(textContent).isNotNull();
@@ -59,7 +57,7 @@ void testTextContentDeserialization() throws Exception {
 	@Test
 	void testContentDeserializationWrongType() throws Exception {
 
-		assertThatThrownBy(() -> mapper.readValue("""
+		assertThatThrownBy(() -> JSON_MAPPER.readValue("""
 				{"type":"WRONG","text":"XXX"}""", McpSchema.TextContent.class))
 			.isInstanceOf(InvalidTypeIdException.class)
 			.hasMessageContaining(
@@ -69,7 +67,7 @@ void testContentDeserializationWrongType() throws Exception {
 	@Test
 	void testImageContent() throws Exception {
 		McpSchema.ImageContent test = new McpSchema.ImageContent(null, null, "base64encodeddata", "image/png");
-		String value = mapper.writeValueAsString(test);
+		String value = JSON_MAPPER.writeValueAsString(test);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -80,7 +78,7 @@ void testImageContent() throws Exception {
 
 	@Test
 	void testImageContentDeserialization() throws Exception {
-		McpSchema.ImageContent imageContent = mapper.readValue("""
+		McpSchema.ImageContent imageContent = JSON_MAPPER.readValue("""
 				{"type":"image","data":"base64encodeddata","mimeType":"image/png","_meta":{"metaKey":"metaValue"}}""",
 				McpSchema.ImageContent.class);
 		assertThat(imageContent).isNotNull();
@@ -93,7 +91,7 @@ void testImageContentDeserialization() throws Exception {
 	@Test
 	void testAudioContent() throws Exception {
 		McpSchema.AudioContent audioContent = new McpSchema.AudioContent(null, "base64encodeddata", "audio/wav");
-		String value = mapper.writeValueAsString(audioContent);
+		String value = JSON_MAPPER.writeValueAsString(audioContent);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -104,7 +102,7 @@ void testAudioContent() throws Exception {
 
 	@Test
 	void testAudioContentDeserialization() throws Exception {
-		McpSchema.AudioContent audioContent = mapper.readValue("""
+		McpSchema.AudioContent audioContent = JSON_MAPPER.readValue("""
 				{"type":"audio","data":"base64encodeddata","mimeType":"audio/wav","_meta":{"metaKey":"metaValue"}}""",
 				McpSchema.AudioContent.class);
 		assertThat(audioContent).isNotNull();
@@ -140,7 +138,7 @@ void testCreateMessageRequestWithMeta() throws Exception {
 			.meta(meta)
 			.build();
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -158,7 +156,7 @@ void testEmbeddedResource() throws Exception {
 
 		McpSchema.EmbeddedResource test = new McpSchema.EmbeddedResource(null, null, resourceContents);
 
-		String value = mapper.writeValueAsString(test);
+		String value = JSON_MAPPER.writeValueAsString(test);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -169,7 +167,7 @@ void testEmbeddedResource() throws Exception {
 
 	@Test
 	void testEmbeddedResourceDeserialization() throws Exception {
-		McpSchema.EmbeddedResource embeddedResource = mapper.readValue(
+		McpSchema.EmbeddedResource embeddedResource = JSON_MAPPER.readValue(
 				"""
 						{"type":"resource","resource":{"uri":"resource://test","mimeType":"text/plain","text":"Sample resource content"},"_meta":{"metaKey":"metaValue"}}""",
 				McpSchema.EmbeddedResource.class);
@@ -189,7 +187,7 @@ void testEmbeddedResourceWithBlobContents() throws Exception {
 
 		McpSchema.EmbeddedResource test = new McpSchema.EmbeddedResource(null, null, resourceContents);
 
-		String value = mapper.writeValueAsString(test);
+		String value = JSON_MAPPER.writeValueAsString(test);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -200,7 +198,7 @@ void testEmbeddedResourceWithBlobContents() throws Exception {
 
 	@Test
 	void testEmbeddedResourceWithBlobContentsDeserialization() throws Exception {
-		McpSchema.EmbeddedResource embeddedResource = mapper.readValue(
+		McpSchema.EmbeddedResource embeddedResource = JSON_MAPPER.readValue(
 				"""
 						{"type":"resource","resource":{"uri":"resource://test","mimeType":"application/octet-stream","blob":"base64encodedblob","_meta":{"metaKey":"metaValue"}}}""",
 				McpSchema.EmbeddedResource.class);
@@ -219,7 +217,7 @@ void testResourceLink() throws Exception {
 		McpSchema.ResourceLink resourceLink = new McpSchema.ResourceLink("main.rs", "Main file",
 				"file:///project/src/main.rs", "Primary application entry point", "text/x-rust", null, null,
 				Map.of("metaKey", "metaValue"));
-		String value = mapper.writeValueAsString(resourceLink);
+		String value = JSON_MAPPER.writeValueAsString(resourceLink);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -231,7 +229,7 @@ void testResourceLink() throws Exception {
 
 	@Test
 	void testResourceLinkDeserialization() throws Exception {
-		McpSchema.ResourceLink resourceLink = mapper.readValue(
+		McpSchema.ResourceLink resourceLink = JSON_MAPPER.readValue(
 				"""
 						{"type":"resource_link","name":"main.rs","uri":"file:///project/src/main.rs","description":"Primary application entry point","mimeType":"text/x-rust","_meta":{"metaKey":"metaValue"}}""",
 				McpSchema.ResourceLink.class);
@@ -254,7 +252,7 @@ void testJSONRPCRequest() throws Exception {
 		McpSchema.JSONRPCRequest request = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, "method_name", 1,
 				params);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -270,7 +268,7 @@ void testJSONRPCNotification() throws Exception {
 		McpSchema.JSONRPCNotification notification = new McpSchema.JSONRPCNotification(McpSchema.JSONRPC_VERSION,
 				"notification_method", params);
 
-		String value = mapper.writeValueAsString(notification);
+		String value = JSON_MAPPER.writeValueAsString(notification);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -285,7 +283,7 @@ void testJSONRPCResponse() throws Exception {
 
 		McpSchema.JSONRPCResponse response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, 1, result, null);
 
-		String value = mapper.writeValueAsString(response);
+		String value = JSON_MAPPER.writeValueAsString(response);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -300,7 +298,7 @@ void testJSONRPCResponseWithError() throws Exception {
 
 		McpSchema.JSONRPCResponse response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, 1, null, error);
 
-		String value = mapper.writeValueAsString(response);
+		String value = JSON_MAPPER.writeValueAsString(response);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -323,7 +321,7 @@ void testInitializeRequest() throws Exception {
 		McpSchema.InitializeRequest request = new McpSchema.InitializeRequest(ProtocolVersions.MCP_2024_11_05,
 				capabilities, clientInfo, meta);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -346,7 +344,7 @@ void testInitializeResult() throws Exception {
 		McpSchema.InitializeResult result = new McpSchema.InitializeResult(ProtocolVersions.MCP_2024_11_05,
 				capabilities, serverInfo, "Server initialized successfully");
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -365,7 +363,7 @@ void testResource() throws Exception {
 		McpSchema.Resource resource = new McpSchema.Resource("resource://test", "Test Resource", "A test resource",
 				"text/plain", annotations);
 
-		String value = mapper.writeValueAsString(resource);
+		String value = JSON_MAPPER.writeValueAsString(resource);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -389,7 +387,7 @@ void testResourceBuilder() throws Exception {
 			.meta(Map.of("metaKey", "metaValue"))
 			.build();
 
-		String value = mapper.writeValueAsString(resource);
+		String value = JSON_MAPPER.writeValueAsString(resource);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -436,7 +434,7 @@ void testResourceTemplate() throws Exception {
 		McpSchema.ResourceTemplate template = new McpSchema.ResourceTemplate("resource://{param}/test", "Test Template",
 				"Test Template", "A test resource template", "text/plain", annotations, meta);
 
-		String value = mapper.writeValueAsString(template);
+		String value = JSON_MAPPER.writeValueAsString(template);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -458,7 +456,7 @@ void testListResourcesResult() throws Exception {
 		McpSchema.ListResourcesResult result = new McpSchema.ListResourcesResult(Arrays.asList(resource1, resource2),
 				"next-cursor", meta);
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -478,7 +476,7 @@ void testListResourceTemplatesResult() throws Exception {
 		McpSchema.ListResourceTemplatesResult result = new McpSchema.ListResourceTemplatesResult(
 				Arrays.asList(template1, template2), "next-cursor");
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -492,7 +490,7 @@ void testReadResourceRequest() throws Exception {
 		McpSchema.ReadResourceRequest request = new McpSchema.ReadResourceRequest("resource://test",
 				Map.of("metaKey", "metaValue"));
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -507,7 +505,7 @@ void testReadResourceRequestWithMeta() throws Exception {
 
 		McpSchema.ReadResourceRequest request = new McpSchema.ReadResourceRequest("resource://test", meta);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -521,7 +519,7 @@ void testReadResourceRequestWithMeta() throws Exception {
 
 	@Test
 	void testReadResourceRequestDeserialization() throws Exception {
-		McpSchema.ReadResourceRequest request = mapper.readValue("""
+		McpSchema.ReadResourceRequest request = JSON_MAPPER.readValue("""
 				{"uri":"resource://test","_meta":{"progressToken":"test-token"}}""",
 				McpSchema.ReadResourceRequest.class);
 
@@ -541,7 +539,7 @@ void testReadResourceResult() throws Exception {
 		McpSchema.ReadResourceResult result = new McpSchema.ReadResourceResult(Arrays.asList(contents1, contents2),
 				Map.of("metaKey", "metaValue"));
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -562,7 +560,7 @@ void testPrompt() throws Exception {
 		McpSchema.Prompt prompt = new McpSchema.Prompt("test-prompt", "Test Prompt", "A test prompt",
 				Arrays.asList(arg1, arg2), Map.of("metaKey", "metaValue"));
 
-		String value = mapper.writeValueAsString(prompt);
+		String value = JSON_MAPPER.writeValueAsString(prompt);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -577,7 +575,7 @@ void testPromptMessage() throws Exception {
 
 		McpSchema.PromptMessage message = new McpSchema.PromptMessage(McpSchema.Role.USER, content);
 
-		String value = mapper.writeValueAsString(message);
+		String value = JSON_MAPPER.writeValueAsString(message);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -598,7 +596,7 @@ void testListPromptsResult() throws Exception {
 		McpSchema.ListPromptsResult result = new McpSchema.ListPromptsResult(Arrays.asList(prompt1, prompt2),
 				"next-cursor");
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -615,7 +613,7 @@ void testGetPromptRequest() throws Exception {
 
 		McpSchema.GetPromptRequest request = new McpSchema.GetPromptRequest("test-prompt", arguments);
 
-		assertThat(mapper.readValue("""
+		assertThat(JSON_MAPPER.readValue("""
 				{"name":"test-prompt","arguments":{"arg1":"value1","arg2":42}}""", McpSchema.GetPromptRequest.class))
 			.isEqualTo(request);
 	}
@@ -631,7 +629,7 @@ void testGetPromptRequestWithMeta() throws Exception {
 
 		McpSchema.GetPromptRequest request = new McpSchema.GetPromptRequest("test-prompt", arguments, meta);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -656,7 +654,7 @@ void testGetPromptResult() throws Exception {
 		McpSchema.GetPromptResult result = new McpSchema.GetPromptResult("A test prompt result",
 				Arrays.asList(message1, message2));
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -696,16 +694,16 @@ void testJsonSchema() throws Exception {
 				""";
 
 		// Deserialize the original string to a JsonSchema object
-		McpSchema.JsonSchema schema = mapper.readValue(schemaJson, McpSchema.JsonSchema.class);
+		McpSchema.JsonSchema schema = JSON_MAPPER.readValue(schemaJson, McpSchema.JsonSchema.class);
 
 		// Serialize the object back to a string
-		String serialized = mapper.writeValueAsString(schema);
+		String serialized = JSON_MAPPER.writeValueAsString(schema);
 
 		// Deserialize again
-		McpSchema.JsonSchema deserialized = mapper.readValue(serialized, McpSchema.JsonSchema.class);
+		McpSchema.JsonSchema deserialized = JSON_MAPPER.readValue(serialized, McpSchema.JsonSchema.class);
 
 		// Serialize one more time and compare with the first serialization
-		String serializedAgain = mapper.writeValueAsString(deserialized);
+		String serializedAgain = JSON_MAPPER.writeValueAsString(deserialized);
 
 		// The two serialized strings should be the same
 		assertThatJson(serializedAgain).when(Option.IGNORING_ARRAY_ORDER).isEqualTo(json(serialized));
@@ -739,16 +737,16 @@ void testJsonSchemaWithDefinitions() throws Exception {
 				""";
 
 		// Deserialize the original string to a JsonSchema object
-		McpSchema.JsonSchema schema = mapper.readValue(schemaJson, McpSchema.JsonSchema.class);
+		McpSchema.JsonSchema schema = JSON_MAPPER.readValue(schemaJson, McpSchema.JsonSchema.class);
 
 		// Serialize the object back to a string
-		String serialized = mapper.writeValueAsString(schema);
+		String serialized = JSON_MAPPER.writeValueAsString(schema);
 
 		// Deserialize again
-		McpSchema.JsonSchema deserialized = mapper.readValue(serialized, McpSchema.JsonSchema.class);
+		McpSchema.JsonSchema deserialized = JSON_MAPPER.readValue(serialized, McpSchema.JsonSchema.class);
 
 		// Serialize one more time and compare with the first serialization
-		String serializedAgain = mapper.writeValueAsString(deserialized);
+		String serializedAgain = JSON_MAPPER.writeValueAsString(deserialized);
 
 		// The two serialized strings should be the same
 		assertThatJson(serializedAgain).when(Option.IGNORING_ARRAY_ORDER).isEqualTo(json(serialized));
@@ -771,9 +769,13 @@ void testTool() throws Exception {
 				}
 				""";
 
-		McpSchema.Tool tool = new McpSchema.Tool("test-tool", "A test tool", schemaJson);
+		McpSchema.Tool tool = McpSchema.Tool.builder()
+			.name("test-tool")
+			.description("A test tool")
+			.inputSchema(JSON_MAPPER, schemaJson)
+			.build();
 
-		String value = mapper.writeValueAsString(tool);
+		String value = JSON_MAPPER.writeValueAsString(tool);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -805,16 +807,20 @@ void testToolWithComplexSchema() throws Exception {
 				}
 				""";
 
-		McpSchema.Tool tool = new McpSchema.Tool("addressTool", "Handles addresses", complexSchemaJson);
+		McpSchema.Tool tool = McpSchema.Tool.builder()
+			.name("addressTool")
+			.title("Handles addresses")
+			.inputSchema(JSON_MAPPER, complexSchemaJson)
+			.build();
 
 		// Serialize the tool to a string
-		String serialized = mapper.writeValueAsString(tool);
+		String serialized = JSON_MAPPER.writeValueAsString(tool);
 
 		// Deserialize back to a Tool object
-		McpSchema.Tool deserializedTool = mapper.readValue(serialized, McpSchema.Tool.class);
+		McpSchema.Tool deserializedTool = JSON_MAPPER.readValue(serialized, McpSchema.Tool.class);
 
 		// Serialize again and compare with first serialization
-		String serializedAgain = mapper.writeValueAsString(deserializedTool);
+		String serializedAgain = JSON_MAPPER.writeValueAsString(deserializedTool);
 
 		// The two serialized strings should be the same
 		assertThatJson(serializedAgain).when(Option.IGNORING_ARRAY_ORDER).isEqualTo(json(serialized));
@@ -841,11 +847,16 @@ void testToolWithMeta() throws Exception {
 				}
 				""";
 
-		McpSchema.JsonSchema schema = mapper.readValue(schemaJson, McpSchema.JsonSchema.class);
+		McpSchema.JsonSchema schema = JSON_MAPPER.readValue(schemaJson, McpSchema.JsonSchema.class);
 		Map meta = Map.of("metaKey", "metaValue");
 
-		McpSchema.Tool tool = new McpSchema.Tool("addressTool", "addressTool", "Handles addresses", schema, null, null,
-				meta);
+		McpSchema.Tool tool = McpSchema.Tool.builder()
+			.name("addressTool")
+			.title("addressTool")
+			.description("Handles addresses")
+			.inputSchema(schema)
+			.meta(meta)
+			.build();
 
 		// Verify that meta value was preserved
 		assertThat(tool.meta()).isNotNull();
@@ -871,9 +882,14 @@ void testToolWithAnnotations() throws Exception {
 		McpSchema.ToolAnnotations annotations = new McpSchema.ToolAnnotations("A test tool", false, false, false, false,
 				false);
 
-		McpSchema.Tool tool = new McpSchema.Tool("test-tool", "A test tool", schemaJson, annotations);
+		McpSchema.Tool tool = McpSchema.Tool.builder()
+			.name("test-tool")
+			.description("A test tool")
+			.inputSchema(JSON_MAPPER, schemaJson)
+			.annotations(annotations)
+			.build();
 
-		String value = mapper.writeValueAsString(tool);
+		String value = JSON_MAPPER.writeValueAsString(tool);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -934,9 +950,14 @@ void testToolWithOutputSchema() throws Exception {
 				}
 				""";
 
-		McpSchema.Tool tool = new McpSchema.Tool("test-tool", "A test tool", inputSchemaJson, outputSchemaJson, null);
+		McpSchema.Tool tool = McpSchema.Tool.builder()
+			.name("test-tool")
+			.description("A test tool")
+			.inputSchema(JSON_MAPPER, inputSchemaJson)
+			.outputSchema(JSON_MAPPER, outputSchemaJson)
+			.build();
 
-		String value = mapper.writeValueAsString(tool);
+		String value = JSON_MAPPER.writeValueAsString(tool);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -996,10 +1017,15 @@ void testToolWithOutputSchemaAndAnnotations() throws Exception {
 		McpSchema.ToolAnnotations annotations = new McpSchema.ToolAnnotations("A test tool with output", true, false,
 				true, false, true);
 
-		McpSchema.Tool tool = new McpSchema.Tool("test-tool", "A test tool", inputSchemaJson, outputSchemaJson,
-				annotations);
+		McpSchema.Tool tool = McpSchema.Tool.builder()
+			.name("test-tool")
+			.description("A test tool")
+			.inputSchema(JSON_MAPPER, inputSchemaJson)
+			.outputSchema(JSON_MAPPER, outputSchemaJson)
+			.annotations(annotations)
+			.build();
 
-		String value = mapper.writeValueAsString(tool);
+		String value = JSON_MAPPER.writeValueAsString(tool);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1063,7 +1089,7 @@ void testToolDeserialization() throws Exception {
 				}
 				""";
 
-		McpSchema.Tool tool = mapper.readValue(toolJson, McpSchema.Tool.class);
+		McpSchema.Tool tool = JSON_MAPPER.readValue(toolJson, McpSchema.Tool.class);
 
 		assertThat(tool).isNotNull();
 		assertThat(tool.name()).isEqualTo("test-tool");
@@ -1097,7 +1123,7 @@ void testToolDeserializationWithoutOutputSchema() throws Exception {
 				}
 				""";
 
-		McpSchema.Tool tool = mapper.readValue(toolJson, McpSchema.Tool.class);
+		McpSchema.Tool tool = JSON_MAPPER.readValue(toolJson, McpSchema.Tool.class);
 
 		assertThat(tool).isNotNull();
 		assertThat(tool.name()).isEqualTo("test-tool");
@@ -1115,7 +1141,7 @@ void testCallToolRequest() throws Exception {
 
 		McpSchema.CallToolRequest request = new McpSchema.CallToolRequest("test-tool", arguments);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1127,14 +1153,14 @@ void testCallToolRequest() throws Exception {
 	@Test
 	void testCallToolRequestJsonArguments() throws Exception {
 
-		McpSchema.CallToolRequest request = new McpSchema.CallToolRequest("test-tool", """
+		McpSchema.CallToolRequest request = new McpSchema.CallToolRequest(JSON_MAPPER, "test-tool", """
 				{
 					"name": "test",
 					"value": 42
 				}
 				""");
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1151,7 +1177,7 @@ void testCallToolRequestWithMeta() throws Exception {
 			.arguments(Map.of("name", "test", "value", 42))
 			.progressToken("tool-progress-123")
 			.build();
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1170,14 +1196,18 @@ void testCallToolRequestBuilderWithJsonArguments() throws Exception {
 		Map meta = new HashMap<>();
 		meta.put("progressToken", "json-builder-789");
 
-		McpSchema.CallToolRequest request = McpSchema.CallToolRequest.builder().name("test-tool").arguments("""
-				{
-					"name": "test",
-					"value": 42
-				}
-				""").meta(meta).build();
+		McpSchema.CallToolRequest request = McpSchema.CallToolRequest.builder()
+			.name("test-tool")
+			.arguments(JSON_MAPPER, """
+					{
+						"name": "test",
+						"value": 42
+					}
+					""")
+			.meta(meta)
+			.build();
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1210,7 +1240,7 @@ void testCallToolResult() throws Exception {
 			.content(Collections.singletonList(content))
 			.build();
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1226,7 +1256,7 @@ void testCallToolResultBuilder() throws Exception {
 			.isError(false)
 			.build();
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1246,7 +1276,7 @@ void testCallToolResultBuilderWithMultipleContents() throws Exception {
 			.isError(false)
 			.build();
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1264,7 +1294,7 @@ void testCallToolResultBuilderWithContentList() throws Exception {
 
 		McpSchema.CallToolResult result = McpSchema.CallToolResult.builder().content(contents).isError(true).build();
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1281,7 +1311,7 @@ void testCallToolResultBuilderWithErrorResult() throws Exception {
 			.isError(true)
 			.build();
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1299,8 +1329,8 @@ void testCallToolResultStringConstructor() throws Exception {
 			.isError(false)
 			.build();
 
-		String value1 = mapper.writeValueAsString(result1);
-		String value2 = mapper.writeValueAsString(result2);
+		String value1 = JSON_MAPPER.writeValueAsString(result1);
+		String value2 = JSON_MAPPER.writeValueAsString(result2);
 
 		// Both should produce the same JSON
 		assertThat(value1).isEqualTo(value2);
@@ -1338,7 +1368,7 @@ void testCreateMessageRequest() throws Exception {
 			.metadata(metadata)
 			.build();
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1359,7 +1389,7 @@ void testCreateMessageResult() throws Exception {
 			.stopReason(McpSchema.CreateMessageResult.StopReason.END_TURN)
 			.build();
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1374,7 +1404,7 @@ void testCreateMessageResultUnknownStopReason() throws Exception {
 		String input = """
 				{"role":"assistant","content":{"type":"text","text":"Assistant response"},"model":"gpt-4","stopReason":"arbitrary value"}""";
 
-		McpSchema.CreateMessageResult value = mapper.readValue(input, McpSchema.CreateMessageResult.class);
+		McpSchema.CreateMessageResult value = JSON_MAPPER.readValue(input, McpSchema.CreateMessageResult.class);
 
 		McpSchema.TextContent expectedContent = new McpSchema.TextContent("Assistant response");
 		McpSchema.CreateMessageResult expected = McpSchema.CreateMessageResult.builder()
@@ -1395,7 +1425,7 @@ void testCreateElicitationRequest() throws Exception {
 					Map.of("foo", Map.of("type", "string"))))
 			.build();
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1411,7 +1441,7 @@ void testCreateElicitationResult() throws Exception {
 			.message(McpSchema.ElicitResult.Action.ACCEPT)
 			.build();
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1434,7 +1464,7 @@ void testElicitRequestWithMeta() throws Exception {
 			.meta(meta)
 			.build();
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1451,7 +1481,7 @@ void testElicitRequestWithMeta() throws Exception {
 	void testPaginatedRequestNoArgs() throws Exception {
 		McpSchema.PaginatedRequest request = new McpSchema.PaginatedRequest();
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1467,7 +1497,7 @@ void testPaginatedRequestNoArgs() throws Exception {
 	void testPaginatedRequestWithCursor() throws Exception {
 		McpSchema.PaginatedRequest request = new McpSchema.PaginatedRequest("cursor123");
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1486,7 +1516,7 @@ void testPaginatedRequestWithMeta() throws Exception {
 
 		McpSchema.PaginatedRequest request = new McpSchema.PaginatedRequest("cursor123", meta);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1500,7 +1530,7 @@ void testPaginatedRequestWithMeta() throws Exception {
 
 	@Test
 	void testPaginatedRequestDeserialization() throws Exception {
-		McpSchema.PaginatedRequest request = mapper.readValue("""
+		McpSchema.PaginatedRequest request = JSON_MAPPER.readValue("""
 				{"cursor":"test-cursor","_meta":{"progressToken":"test-token"}}""", McpSchema.PaginatedRequest.class);
 
 		assertThat(request.cursor()).isEqualTo("test-cursor");
@@ -1518,7 +1548,7 @@ void testCompleteRequest() throws Exception {
 
 		McpSchema.CompleteRequest request = new McpSchema.CompleteRequest(promptRef, argument);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1542,7 +1572,7 @@ void testCompleteRequestWithMeta() throws Exception {
 
 		McpSchema.CompleteRequest request = new McpSchema.CompleteRequest(resourceRef, argument, meta, null);
 
-		String value = mapper.writeValueAsString(request);
+		String value = JSON_MAPPER.writeValueAsString(request);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1561,7 +1591,7 @@ void testCompleteRequestWithMeta() throws Exception {
 	void testRoot() throws Exception {
 		McpSchema.Root root = new McpSchema.Root("file:///path/to/root", "Test Root", Map.of("metaKey", "metaValue"));
 
-		String value = mapper.writeValueAsString(root);
+		String value = JSON_MAPPER.writeValueAsString(root);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1577,7 +1607,7 @@ void testListRootsResult() throws Exception {
 
 		McpSchema.ListRootsResult result = new McpSchema.ListRootsResult(Arrays.asList(root1, root2), "next-cursor");
 
-		String value = mapper.writeValueAsString(result);
+		String value = JSON_MAPPER.writeValueAsString(result);
 
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
@@ -1595,7 +1625,7 @@ void testProgressNotificationWithMessage() throws Exception {
 		McpSchema.ProgressNotification notification = new McpSchema.ProgressNotification("progress-token-123", 0.5, 1.0,
 				"Processing file 1 of 2", Map.of("key", "value"));
 
-		String value = mapper.writeValueAsString(notification);
+		String value = JSON_MAPPER.writeValueAsString(notification);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
@@ -1606,7 +1636,7 @@ void testProgressNotificationWithMessage() throws Exception {
 
 	@Test
 	void testProgressNotificationDeserialization() throws Exception {
-		McpSchema.ProgressNotification notification = mapper.readValue(
+		McpSchema.ProgressNotification notification = JSON_MAPPER.readValue(
 				"""
 						{"progressToken":"token-456","progress":0.75,"total":1.0,"message":"Almost done","_meta":{"key":"value"}}""",
 				McpSchema.ProgressNotification.class);
@@ -1623,7 +1653,7 @@ void testProgressNotificationWithoutMessage() throws Exception {
 		McpSchema.ProgressNotification notification = new McpSchema.ProgressNotification("progress-token-789", 0.25,
 				null, null);
 
-		String value = mapper.writeValueAsString(notification);
+		String value = JSON_MAPPER.writeValueAsString(notification);
 		assertThatJson(value).when(Option.IGNORING_ARRAY_ORDER)
 			.when(Option.IGNORING_EXTRA_ARRAY_ITEMS)
 			.isObject()
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java b/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java
new file mode 100644
index 000000000..ef7cd2737
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java
@@ -0,0 +1,97 @@
+package io.modelcontextprotocol.spec.json.gson;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.ToNumberPolicy;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Test-only Gson-based implementation of McpJsonMapper. This lives under src/test/java so
+ * it doesn't affect production code or dependencies.
+ */
+public final class GsonMcpJsonMapper implements McpJsonMapper {
+
+	private final Gson gson;
+
+	public GsonMcpJsonMapper() {
+		this(new GsonBuilder().serializeNulls()
+			// Ensure numeric values in untyped (Object) fields preserve integral numbers
+			// as Long
+			.setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
+			.setNumberToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
+			.create());
+	}
+
+	public GsonMcpJsonMapper(Gson gson) {
+		if (gson == null) {
+			throw new IllegalArgumentException("Gson must not be null");
+		}
+		this.gson = gson;
+	}
+
+	public Gson getGson() {
+		return gson;
+	}
+
+	@Override
+	public  T readValue(String content, Class type) throws IOException {
+		try {
+			return gson.fromJson(content, type);
+		}
+		catch (Exception e) {
+			throw new IOException("Failed to deserialize JSON", e);
+		}
+	}
+
+	@Override
+	public  T readValue(byte[] content, Class type) throws IOException {
+		return readValue(new String(content, StandardCharsets.UTF_8), type);
+	}
+
+	@Override
+	public  T readValue(String content, TypeRef type) throws IOException {
+		try {
+			return gson.fromJson(content, type.getType());
+		}
+		catch (Exception e) {
+			throw new IOException("Failed to deserialize JSON", e);
+		}
+	}
+
+	@Override
+	public  T readValue(byte[] content, TypeRef type) throws IOException {
+		return readValue(new String(content, StandardCharsets.UTF_8), type);
+	}
+
+	@Override
+	public  T convertValue(Object fromValue, Class type) {
+		String json = gson.toJson(fromValue);
+		return gson.fromJson(json, type);
+	}
+
+	@Override
+	public  T convertValue(Object fromValue, TypeRef type) {
+		String json = gson.toJson(fromValue);
+		return gson.fromJson(json, type.getType());
+	}
+
+	@Override
+	public String writeValueAsString(Object value) throws IOException {
+		try {
+			return gson.toJson(value);
+		}
+		catch (Exception e) {
+			throw new IOException("Failed to serialize to JSON", e);
+		}
+	}
+
+	@Override
+	public byte[] writeValueAsBytes(Object value) throws IOException {
+		return writeValueAsString(value).getBytes(StandardCharsets.UTF_8);
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java b/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
new file mode 100644
index 000000000..4f1dffe1d
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
@@ -0,0 +1,132 @@
+package io.modelcontextprotocol.spec.json.gson;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.json.TypeRef;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class GsonMcpJsonMapperTests {
+
+	record Person(String name, int age) {
+	}
+
+	@Test
+	void roundTripSimplePojo() throws IOException {
+		var mapper = new GsonMcpJsonMapper();
+
+		var input = new Person("Alice", 30);
+		String json = mapper.writeValueAsString(input);
+		assertNotNull(json);
+		assertTrue(json.contains("\"Alice\""));
+		assertTrue(json.contains("\"age\""));
+
+		var decoded = mapper.readValue(json, Person.class);
+		assertEquals(input, decoded);
+
+		byte[] bytes = mapper.writeValueAsBytes(input);
+		assertNotNull(bytes);
+		var decodedFromBytes = mapper.readValue(bytes, Person.class);
+		assertEquals(input, decodedFromBytes);
+	}
+
+	@Test
+	void readWriteParameterizedTypeWithTypeRef() throws IOException {
+		var mapper = new GsonMcpJsonMapper();
+		String json = "[\"a\", \"b\", \"c\"]";
+
+		List list = mapper.readValue(json, new TypeRef>() {
+		});
+		assertEquals(List.of("a", "b", "c"), list);
+
+		String encoded = mapper.writeValueAsString(list);
+		assertTrue(encoded.startsWith("["));
+		assertTrue(encoded.contains("\"a\""));
+	}
+
+	@Test
+	void convertValueMapToRecordAndParameterized() {
+		var mapper = new GsonMcpJsonMapper();
+		Map src = Map.of("name", "Bob", "age", 42);
+
+		// Convert to simple record
+		Person person = mapper.convertValue(src, Person.class);
+		assertEquals(new Person("Bob", 42), person);
+
+		// Convert to parameterized Map
+		Map toMap = mapper.convertValue(person, new TypeRef>() {
+		});
+		assertEquals("Bob", toMap.get("name"));
+		assertEquals(42.0, ((Number) toMap.get("age")).doubleValue(), 0.0); // Gson may
+		// emit double
+		// for
+		// primitives
+	}
+
+	@Test
+	void deserializeJsonRpcMessageRequestUsingCustomMapper() throws IOException {
+		var mapper = new GsonMcpJsonMapper();
+
+		String json = """
+				{
+				  "jsonrpc": "2.0",
+				  "id": 1,
+				  "method": "ping",
+				  "params": { "x": 1, "y": "z" }
+				}
+				""";
+
+		var msg = McpSchema.deserializeJsonRpcMessage(mapper, json);
+		assertTrue(msg instanceof McpSchema.JSONRPCRequest);
+
+		var req = (McpSchema.JSONRPCRequest) msg;
+		assertEquals("2.0", req.jsonrpc());
+		assertEquals("ping", req.method());
+		assertNotNull(req.id());
+		assertEquals("1", req.id().toString());
+
+		assertNotNull(req.params());
+		assertInstanceOf(Map.class, req.params());
+		@SuppressWarnings("unchecked")
+		var params = (Map) req.params();
+		assertEquals(1.0, ((Number) params.get("x")).doubleValue(), 0.0);
+		assertEquals("z", params.get("y"));
+	}
+
+	@Test
+	void integrateWithMcpSchemaStaticMapperForStringParsing() {
+		var gsonMapper = new GsonMcpJsonMapper();
+
+		// Tool builder parsing of input/output schema strings
+		var tool = McpSchema.Tool.builder().name("echo").description("Echo tool").inputSchema(gsonMapper, """
+				{
+				  "type": "object",
+				  "properties": { "x": { "type": "integer" } },
+				  "required": ["x"]
+				}
+				""").outputSchema(gsonMapper, """
+				{
+				  "type": "object",
+				  "properties": { "y": { "type": "string" } }
+				}
+				""").build();
+
+		assertNotNull(tool.inputSchema());
+		assertNotNull(tool.outputSchema());
+		assertTrue(tool.outputSchema().containsKey("properties"));
+
+		// CallToolRequest builder parsing of JSON arguments string
+		var call = McpSchema.CallToolRequest.builder().name("echo").arguments(gsonMapper, "{\"x\": 123}").build();
+
+		assertEquals("echo", call.name());
+		assertNotNull(call.arguments());
+		assertTrue(call.arguments().get("x") instanceof Number);
+		assertEquals(123.0, ((Number) call.arguments().get("x")).doubleValue(), 0.0);
+
+	}
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java b/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
index 4de9363c2..d5ef8a91c 100644
--- a/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
+++ b/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
@@ -16,7 +16,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.json.TypeRef;
 
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSession;
@@ -259,7 +259,7 @@ private static class MockMcpSession implements McpSession {
 		private boolean shouldFailPing = false;
 
 		@Override
-		public  Mono sendRequest(String method, Object requestParams, TypeReference typeRef) {
+		public  Mono sendRequest(String method, Object requestParams, TypeRef typeRef) {
 			if (McpSchema.METHOD_PING.equals(method)) {
 				pingCount.incrementAndGet();
 				if (shouldFailPing) {
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java b/mcp/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
new file mode 100644
index 000000000..911506e01
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
@@ -0,0 +1,12 @@
+package io.modelcontextprotocol.util;
+
+import io.modelcontextprotocol.json.McpJsonMapper;
+
+public final class McpJsonMapperUtils {
+
+	private McpJsonMapperUtils() {
+	}
+
+	public static final McpJsonMapper JSON_MAPPER = McpJsonMapper.getDefault();
+
+}
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java b/mcp/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java
new file mode 100644
index 000000000..ce8755223
--- /dev/null
+++ b/mcp/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java
@@ -0,0 +1,15 @@
+package io.modelcontextprotocol.util;
+
+import io.modelcontextprotocol.spec.McpSchema;
+
+import java.util.Collections;
+
+public final class ToolsUtils {
+
+	private ToolsUtils() {
+	}
+
+	public static final McpSchema.JsonSchema EMPTY_JSON_SCHEMA = new McpSchema.JsonSchema("object",
+			Collections.emptyMap(), null, null, null, null);
+
+}
diff --git a/pom.xml b/pom.xml
index 9990a4663..f60a9aca1 100644
--- a/pom.xml
+++ b/pom.xml
@@ -103,6 +103,8 @@
 	
 		mcp-bom
 		mcp
+        mcp-json-jackson2
+        mcp-json
 		mcp-spring/mcp-spring-webflux
 		mcp-spring/mcp-spring-webmvc
 		mcp-test

From 1499df22c7023aa257223143a5dcf5b1db7ef80d Mon Sep 17 00:00:00 2001
From: Sergio del Amo 
Date: Wed, 17 Sep 2025 11:32:08 +0200
Subject: [PATCH 073/125] extract mcp-core (#557)

* extract mcp-core
  - This change extracts classes previously in `mcp` to `mcp-core`; a new module which does not depend on `mcp-json-jackon2`.
  - `mcp` module is now an umbrella module that brings `mcp-json-jackon2` and `mcp-core`
* add mcp-core to bom

BREAKING CHANGE: All source code in the previously `mcp` module is moved to the `mcp-core`.  the `mcp` now is just an aggregation for `mcp-core` + `mcp-json-jackson2` for backward compatibility.
This change won't affect the end users, but will cause conflicts for the existing PRs.
---
 mcp-bom/pom.xml                               |   7 +
 mcp-core/pom.xml                              | 235 ++++++++++++++++++
 .../client/LifecycleInitializer.java          |   0
 .../client/McpAsyncClient.java                |   0
 .../client/McpClient.java                     |   0
 .../client/McpClientFeatures.java             |   0
 .../client/McpSyncClient.java                 |   0
 .../HttpClientSseClientTransport.java         |   0
 .../HttpClientStreamableHttpTransport.java    |   0
 .../client/transport/ResponseSubscribers.java |   0
 .../client/transport/ServerParameters.java    |   0
 .../transport/StdioClientTransport.java       |   0
 ...ngMcpAsyncHttpClientRequestCustomizer.java |   0
 ...ingMcpSyncHttpClientRequestCustomizer.java |   0
 .../McpAsyncHttpClientRequestCustomizer.java  |   0
 .../McpSyncHttpClientRequestCustomizer.java   |   0
 .../common/DefaultMcpTransportContext.java    |   0
 .../common/McpTransportContext.java           |   0
 .../DefaultMcpStatelessServerHandler.java     |   0
 .../server/McpAsyncServer.java                |   0
 .../server/McpAsyncServerExchange.java        |   0
 .../server/McpInitRequestHandler.java         |   0
 .../server/McpNotificationHandler.java        |   0
 .../server/McpRequestHandler.java             |   0
 .../server/McpServer.java                     |   0
 .../server/McpServerFeatures.java             |   0
 .../server/McpStatelessAsyncServer.java       |   0
 .../McpStatelessNotificationHandler.java      |   0
 .../server/McpStatelessRequestHandler.java    |   0
 .../server/McpStatelessServerFeatures.java    |   0
 .../server/McpStatelessServerHandler.java     |   0
 .../server/McpStatelessSyncServer.java        |   0
 .../server/McpSyncServer.java                 |   0
 .../server/McpSyncServerExchange.java         |   0
 .../server/McpTransportContextExtractor.java  |   0
 ...HttpServletSseServerTransportProvider.java |   0
 .../HttpServletStatelessServerTransport.java  |   0
 ...vletStreamableServerTransportProvider.java |   0
 .../StdioServerTransportProvider.java         |   0
 ...aultMcpStreamableServerSessionFactory.java |   0
 .../spec/DefaultMcpTransportSession.java      |   0
 .../spec/DefaultMcpTransportStream.java       |   0
 .../spec/HttpHeaders.java                     |   0
 .../spec/JsonSchemaValidator.java             |   0
 .../spec/McpClientSession.java                |   0
 .../spec/McpClientTransport.java              |   0
 .../modelcontextprotocol/spec/McpError.java   |   0
 .../spec/McpLoggableSession.java              |   0
 .../modelcontextprotocol/spec/McpSchema.java  |   0
 .../spec/McpServerSession.java                |   0
 .../spec/McpServerTransport.java              |   0
 .../spec/McpServerTransportProvider.java      |   0
 .../spec/McpServerTransportProviderBase.java  |   0
 .../modelcontextprotocol/spec/McpSession.java |   0
 .../spec/McpStatelessServerTransport.java     |   0
 .../spec/McpStreamableServerSession.java      |   0
 .../spec/McpStreamableServerTransport.java    |   0
 .../McpStreamableServerTransportProvider.java |   0
 .../spec/McpTransport.java                    |   0
 .../spec/McpTransportException.java           |   0
 .../spec/McpTransportSession.java             |   0
 .../McpTransportSessionNotFoundException.java |   0
 .../spec/McpTransportStream.java              |   0
 .../spec/MissingMcpTransportSession.java      |   0
 .../spec/ProtocolVersions.java                |   0
 .../io/modelcontextprotocol/util/Assert.java  |   0
 .../DeafaultMcpUriTemplateManagerFactory.java |   0
 .../util/DefaultMcpUriTemplateManager.java    |   0
 .../util/KeepAliveScheduler.java              |   0
 .../util/McpUriTemplateManager.java           |   0
 .../util/McpUriTemplateManagerFactory.java    |   0
 .../io/modelcontextprotocol/util/Utils.java   |   0
 .../McpUriTemplateManagerTests.java           |   0
 .../MockMcpClientTransport.java               |   0
 .../MockMcpServerTransport.java               |   0
 .../MockMcpServerTransportProvider.java       |   0
 ...AbstractMcpAsyncClientResiliencyTests.java |   0
 .../client/AbstractMcpAsyncClientTests.java   |   0
 .../client/AbstractMcpSyncClientTests.java    |   0
 ...eamableHttpAsyncClientResiliencyTests.java |   0
 ...pClientStreamableHttpAsyncClientTests.java |   0
 ...tpClientStreamableHttpSyncClientTests.java |   0
 ...pSseMcpAsyncClientLostConnectionTests.java |   0
 .../client/HttpSseMcpAsyncClientTests.java    |   0
 .../client/HttpSseMcpSyncClientTests.java     |   0
 .../client/LifecycleInitializerTests.java     |   0
 .../McpAsyncClientResponseHandlerTests.java   |   0
 .../client/McpAsyncClientTests.java           |   0
 .../client/McpClientProtocolVersionTests.java |   0
 .../client/ServerParameterUtils.java          |   0
 .../client/StdioMcpAsyncClientTests.java      |   0
 .../client/StdioMcpSyncClientTests.java       |   0
 .../HttpClientSseClientTransportTests.java    |   0
 ...bleHttpTransportEmptyJsonResponseTest.java |   0
 ...eamableHttpTransportErrorHandlingTest.java |   0
 ...HttpClientStreamableHttpTransportTest.java |   0
 ...pAsyncHttpClientRequestCustomizerTest.java |   0
 ...cpSyncHttpClientRequestCustomizerTest.java |   0
 ...erMcpTransportContextIntegrationTests.java |   0
 ...erMcpTransportContextIntegrationTests.java |   0
 .../server/AbstractMcpAsyncServerTests.java   |   0
 ...stractMcpClientServerIntegrationTests.java |   0
 .../server/AbstractMcpSyncServerTests.java    |   0
 .../AsyncToolSpecificationBuilderTest.java    |   0
 .../HttpServletSseIntegrationTests.java       |   0
 .../HttpServletStatelessIntegrationTests.java |   0
 ...HttpServletStreamableAsyncServerTests.java |   0
 ...HttpServletStreamableIntegrationTests.java |   0
 .../HttpServletStreamableSyncServerTests.java |   0
 .../server/McpAsyncServerExchangeTests.java   |   0
 .../server/McpCompletionTests.java            |   0
 .../server/McpServerProtocolVersionTests.java |   0
 .../server/McpSyncServerExchangeTests.java    |   0
 .../server/ResourceTemplateListingTest.java   |   0
 .../server/ServletSseMcpAsyncServerTests.java |   0
 .../server/ServletSseMcpSyncServerTests.java  |   0
 .../server/StdioMcpAsyncServerTests.java      |   0
 .../server/StdioMcpSyncServerTests.java       |   0
 .../SyncToolSpecificationBuilderTest.java     |   0
 ...ervletSseServerCustomContextPathTests.java |   0
 .../transport/McpTestServletFilter.java       |   0
 .../StdioServerTransportProviderTests.java    |   0
 .../server/transport/TomcatTestUtil.java      |   0
 .../spec/ArgumentException.java               |   0
 .../spec/DefaultJsonSchemaValidatorTests.java |   0
 .../spec/JSONRPCRequestMcpValidationTest.java |   0
 .../spec/McpClientSessionTests.java           |   0
 .../spec/McpSchemaTests.java                  |   0
 .../spec/PromptReferenceEqualsTest.java       |   0
 .../spec/json/gson/GsonMcpJsonMapper.java     |   0
 .../json/gson/GsonMcpJsonMapperTests.java     |   0
 .../util/AssertTests.java                     |   0
 .../util/KeepAliveSchedulerTests.java         |   0
 .../util/McpJsonMapperUtils.java              |   0
 .../modelcontextprotocol/util/ToolsUtils.java |   0
 .../modelcontextprotocol/util/UtilsTests.java |   0
 .../src/test/resources/logback.xml            |   0
 mcp/pom.xml                                   | 154 +-----------
 pom.xml                                       |   1 +
 139 files changed, 246 insertions(+), 151 deletions(-)
 create mode 100644 mcp-core/pom.xml
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/McpClient.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/ServerParameters.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpServer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpError.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpSchema.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpTransport.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/util/Assert.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManager.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java (100%)
 rename {mcp => mcp-core}/src/main/java/io/modelcontextprotocol/util/Utils.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientResiliencyTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/util/AssertTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java (100%)
 rename {mcp => mcp-core}/src/test/java/io/modelcontextprotocol/util/UtilsTests.java (100%)
 rename {mcp => mcp-core}/src/test/resources/logback.xml (100%)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index b7ea52639..daa539011 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -27,6 +27,13 @@
     
         
             
+            
+                io.modelcontextprotocol.sdk
+                mcp-core
+                ${project.version}
+            
+
+            
             
                 io.modelcontextprotocol.sdk
                 mcp
diff --git a/mcp-core/pom.xml b/mcp-core/pom.xml
new file mode 100644
index 000000000..52d5bf58a
--- /dev/null
+++ b/mcp-core/pom.xml
@@ -0,0 +1,235 @@
+
+
+	4.0.0
+	
+		io.modelcontextprotocol.sdk
+		mcp-parent
+		0.13.0-SNAPSHOT
+	
+	mcp-core
+	jar
+	Java MCP SDK Core
+	Core classes of the Java SDK implementation of the Model Context Protocol, enabling seamless integration with language models and AI tools
+	https://github.com/modelcontextprotocol/java-sdk
+
+	
+		https://github.com/modelcontextprotocol/java-sdk
+		git://github.com/modelcontextprotocol/java-sdk.git
+		git@github.com/modelcontextprotocol/java-sdk.git
+	
+
+	
+		
+			
+				biz.aQute.bnd
+				bnd-maven-plugin
+				${bnd-maven-plugin.version}
+				
+					
+						bnd-process
+						
+							bnd-process
+						
+						
+							
+							
+						
+					
+				
+			
+
+			
+				org.apache.maven.plugins
+				maven-jar-plugin
+				
+					
+						${project.build.outputDirectory}/META-INF/MANIFEST.MF
+					
+				
+			
+		
+	
+
+	
+        
+            io.modelcontextprotocol.sdk
+            mcp-json
+            0.13.0-SNAPSHOT
+        
+
+		
+			org.slf4j
+			slf4j-api
+			${slf4j-api.version}
+		
+
+		
+			com.fasterxml.jackson.core
+			jackson-annotations
+			${jackson.version}
+		
+
+		
+			io.projectreactor
+			reactor-core
+		
+
+
+		
+		
+			jakarta.servlet
+			jakarta.servlet-api
+			${jakarta.servlet.version}
+			provided
+		
+
+		
+        
+            io.modelcontextprotocol.sdk
+            mcp-json-jackson2
+            0.13.0-SNAPSHOT
+            test
+        
+
+		
+			org.springframework
+			spring-webmvc
+			${springframework.version}
+			test
+		
+
+
+		
+			io.projectreactor.netty
+			reactor-netty-http
+			test
+		
+
+		
+		
+			org.springframework
+			spring-context
+			${springframework.version}
+			test
+		
+
+		
+			org.springframework
+			spring-test
+			${springframework.version}
+			test
+		
+
+		
+			org.assertj
+			assertj-core
+			${assert4j.version}
+			test
+		
+		
+			org.junit.jupiter
+			junit-jupiter-api
+			${junit.version}
+			test
+		
+		
+			org.junit.jupiter
+			junit-jupiter-params
+			${junit.version}
+			test
+		
+		
+			org.mockito
+			mockito-core
+			${mockito.version}
+			test
+		
+
+		
+		
+			net.bytebuddy
+			byte-buddy
+			${byte-buddy.version}
+			test
+		
+		
+			io.projectreactor
+			reactor-test
+			test
+		
+		
+			org.testcontainers
+			junit-jupiter
+			${testcontainers.version}
+			test
+		
+
+		
+			org.awaitility
+			awaitility
+			${awaitility.version}
+			test
+		
+
+		
+			ch.qos.logback
+			logback-classic
+			${logback.version}
+			test
+		
+
+		
+			net.javacrumbs.json-unit
+			json-unit-assertj
+			${json-unit-assertj.version}
+			test
+		
+
+		
+		
+			org.apache.tomcat.embed
+			tomcat-embed-core
+			${tomcat.version}
+			test
+		
+		
+			org.apache.tomcat.embed
+			tomcat-embed-websocket
+			${tomcat.version}
+			test
+		
+
+		
+			org.testcontainers
+			toxiproxy
+			${toxiproxy.version}
+			test
+		
+
+        
+        
+            com.google.code.gson
+            gson
+            2.10.1
+            test
+        
+	
+
+
+
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/McpClient.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/ResponseSubscribers.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/ServerParameters.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/ServerParameters.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/ServerParameters.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/ServerParameters.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/StdioClientTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpAsyncHttpClientRequestCustomizer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/client/transport/customizer/McpSyncHttpClientRequestCustomizer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java b/mcp-core/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/common/DefaultMcpTransportContext.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java b/mcp-core/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/common/McpTransportContext.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpInitRequestHandler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpNotificationHandler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpRequestHandler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessNotificationHandler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessRequestHandler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerHandler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/McpTransportContextExtractor.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStatelessServerTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/server/transport/StdioServerTransportProvider.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/DefaultMcpStreamableServerSessionFactory.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/DefaultMcpTransportStream.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/JsonSchemaValidator.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpError.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpLoggableSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProvider.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerTransportProviderBase.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerTransportProvider.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransport.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportException.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionNotFoundException.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportStream.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/MissingMcpTransportSession.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/Assert.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/util/Assert.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManager.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManager.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManager.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManager.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/McpUriTemplateManagerFactory.java
diff --git a/mcp/src/main/java/io/modelcontextprotocol/util/Utils.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java
similarity index 100%
rename from mcp/src/main/java/io/modelcontextprotocol/util/Utils.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java b/mcp-core/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/MockMcpClientTransport.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java b/mcp-core/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/MockMcpServerTransport.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java b/mcp-core/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/MockMcpServerTransportProvider.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientResiliencyTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientResiliencyTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientResiliencyTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientResiliencyTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientResponseHandlerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/StdioMcpAsyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/StdioMcpSyncClientTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportErrorHandlingTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpAsyncHttpClientRequestCustomizerTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/client/transport/customizer/DelegatingMcpSyncHttpClientRequestCustomizerTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/common/SyncServerMcpTransportContextIntegrationTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableAsyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableSyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/McpAsyncServerExchangeTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/McpServerProtocolVersionTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/McpSyncServerExchangeTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/ResourceTemplateListingTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/ServletSseMcpAsyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/ServletSseMcpSyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/StdioMcpAsyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/StdioMcpSyncServerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/transport/HttpServletSseServerCustomContextPathTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/transport/StdioServerTransportProviderTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/ArgumentException.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapper.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/AssertTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/util/AssertTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/util/AssertTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/util/AssertTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/util/KeepAliveSchedulerTests.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java b/mcp-core/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java b/mcp-core/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java
diff --git a/mcp/src/test/java/io/modelcontextprotocol/util/UtilsTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/util/UtilsTests.java
similarity index 100%
rename from mcp/src/test/java/io/modelcontextprotocol/util/UtilsTests.java
rename to mcp-core/src/test/java/io/modelcontextprotocol/util/UtilsTests.java
diff --git a/mcp/src/test/resources/logback.xml b/mcp-core/src/test/resources/logback.xml
similarity index 100%
rename from mcp/src/test/resources/logback.xml
rename to mcp-core/src/test/resources/logback.xml
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 6ba402a4d..438c7535c 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -70,158 +70,10 @@
             mcp-json-jackson2
             0.13.0-SNAPSHOT
         
-
-		
-			org.slf4j
-			slf4j-api
-			${slf4j-api.version}
-		
-
-		
-			com.fasterxml.jackson.core
-			jackson-annotations
-			${jackson.version}
-		
-
-		
-			io.projectreactor
-			reactor-core
-		
-
-
-		
-		
-			jakarta.servlet
-			jakarta.servlet-api
-			${jakarta.servlet.version}
-			provided
-		
-
-		
-
-		
-			org.springframework
-			spring-webmvc
-			${springframework.version}
-			test
-		
-
-
-		
-			io.projectreactor.netty
-			reactor-netty-http
-			test
-		
-
-		
-		
-			org.springframework
-			spring-context
-			${springframework.version}
-			test
-		
-
-		
-			org.springframework
-			spring-test
-			${springframework.version}
-			test
-		
-
-		
-			org.assertj
-			assertj-core
-			${assert4j.version}
-			test
-		
-		
-			org.junit.jupiter
-			junit-jupiter-api
-			${junit.version}
-			test
-		
-		
-			org.junit.jupiter
-			junit-jupiter-params
-			${junit.version}
-			test
-		
-		
-			org.mockito
-			mockito-core
-			${mockito.version}
-			test
-		
-
-		
-		
-			net.bytebuddy
-			byte-buddy
-			${byte-buddy.version}
-			test
-		
-		
-			io.projectreactor
-			reactor-test
-			test
-		
-		
-			org.testcontainers
-			junit-jupiter
-			${testcontainers.version}
-			test
-		
-
-		
-			org.awaitility
-			awaitility
-			${awaitility.version}
-			test
-		
-
-		
-			ch.qos.logback
-			logback-classic
-			${logback.version}
-			test
-		
-
-		
-			net.javacrumbs.json-unit
-			json-unit-assertj
-			${json-unit-assertj.version}
-			test
-		
-
-		
-		
-			org.apache.tomcat.embed
-			tomcat-embed-core
-			${tomcat.version}
-			test
-		
-		
-			org.apache.tomcat.embed
-			tomcat-embed-websocket
-			${tomcat.version}
-			test
-		
-
-		
-			org.testcontainers
-			toxiproxy
-			${toxiproxy.version}
-			test
-		
-
-        
         
-            com.google.code.gson
-            gson
-            2.10.1
-            test
+            io.modelcontextprotocol.sdk
+            mcp-core
+            0.13.0-SNAPSHOT
         
 	
 
diff --git a/pom.xml b/pom.xml
index f60a9aca1..388fc6d9b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -103,6 +103,7 @@
 	
 		mcp-bom
 		mcp
+        mcp-core
         mcp-json-jackson2
         mcp-json
 		mcp-spring/mcp-spring-webflux

From 8ac7eae47cc8dba4794ab3950e34417d6f6c665b Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Wed, 17 Sep 2025 12:26:55 +0200
Subject: [PATCH 074/125] refactor: standardize test parameterization and fix
 package naming (#556)

- Replace @ValueSource with @MethodSource for parameterized tests
- Add clientsForTesting() methods to provide test arguments consistently
- Remove hardcoded Spring-related labels from framework-agnostic mcp-test module
- Move mcp-test's utility classes from io.modelcontextprotocol.utils to io.modelcontextprotocol.util

Signed-off-by: Christian Tzolov 
---
 ...stractMcpClientServerIntegrationTests.java | 56 +++++++++----------
 .../HttpServletSseIntegrationTests.java       |  6 ++
 ...HttpServletStreamableIntegrationTests.java |  6 ++
 .../WebFluxSseIntegrationTests.java           |  7 +++
 .../WebFluxStatelessIntegrationTests.java     |  7 +++
 .../WebFluxStreamableIntegrationTests.java    |  7 +++
 .../WebFluxSseClientTransportTests.java       |  2 +-
 ...cpStreamableAsyncServerTransportTests.java |  3 +-
 ...McpStreamableSyncServerTransportTests.java |  2 +-
 .../server/WebMvcSseIntegrationTests.java     |  7 +++
 .../WebMvcStatelessIntegrationTests.java      |  7 +++
 .../WebMvcStreamableIntegrationTests.java     |  7 +++
 ...stractMcpClientServerIntegrationTests.java | 55 +++++++++---------
 .../AbstractStatelessIntegrationTests.java    | 25 +++++----
 .../client/AbstractMcpAsyncClientTests.java   |  4 +-
 .../server/AbstractMcpAsyncServerTests.java   |  2 +-
 .../server/AbstractMcpSyncServerTests.java    |  3 +-
 .../{utils => util}/McpJsonMapperUtils.java   |  2 +-
 .../{utils => util}/ToolsUtils.java           |  2 +-
 19 files changed, 134 insertions(+), 76 deletions(-)
 rename mcp-test/src/main/java/io/modelcontextprotocol/{utils => util}/McpJsonMapperUtils.java (84%)
 rename mcp-test/src/main/java/io/modelcontextprotocol/{utils => util}/ToolsUtils.java (88%)

diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index d54a5bd43..cd6e8950f 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -46,6 +46,7 @@
 import io.modelcontextprotocol.util.Utils;
 import net.javacrumbs.jsonunit.core.Option;
 import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
@@ -70,7 +71,7 @@ public abstract class AbstractMcpClientServerIntegrationTests {
 	abstract protected McpServer.SyncSpecification prepareSyncServerBuilder();
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void simple(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -78,7 +79,6 @@ void simple(String clientType) {
 		var server = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.requestTimeout(Duration.ofSeconds(1000))
 			.build();
-
 		try (
 				// Create client without sampling capabilities
 				var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
@@ -97,7 +97,7 @@ void simple(String clientType) {
 	// Sampling Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -133,7 +133,7 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -202,7 +202,7 @@ void testCreateMessageSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws InterruptedException {
 
 		// Client
@@ -282,7 +282,7 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageWithRequestTimeoutFail(String clientType) throws InterruptedException {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -348,7 +348,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 	// Elicitation Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -380,7 +380,7 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -437,7 +437,7 @@ void testCreateElicitationSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -498,7 +498,7 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 
 		var latch = new CountDownLatch(1);
@@ -569,7 +569,7 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 	// Roots Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testRootsSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -617,7 +617,7 @@ void testRootsSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testRootsWithoutCapability(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -656,7 +656,7 @@ void testRootsWithoutCapability(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testRootsNotificationWithEmptyRootsList(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -686,7 +686,7 @@ void testRootsNotificationWithEmptyRootsList(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testRootsWithMultipleHandlers(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -720,7 +720,7 @@ void testRootsWithMultipleHandlers(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testRootsServerCloseWithActiveSubscription(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -755,7 +755,7 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 	// Tools Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testToolCallSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -806,7 +806,7 @@ void testToolCallSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -844,7 +844,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -901,7 +901,7 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testToolListChangeHandlingSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -994,7 +994,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testInitialize(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -1015,7 +1015,7 @@ void testInitialize(String clientType) {
 	// Logging Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testLoggingNotification(String clientType) throws InterruptedException {
 		int expectedNotificationsCount = 3;
 		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
@@ -1128,7 +1128,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 	// Progress Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testProgressNotification(String clientType) throws InterruptedException {
 		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
 											// token
@@ -1234,7 +1234,7 @@ void testProgressNotification(String clientType) throws InterruptedException {
 	// Completion Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : Completion call")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -1256,7 +1256,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 							List.of(new PromptArgument("language", "Language", "string", false))),
 					(mcpSyncServerExchange, getPromptRequest) -> null))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.build()) {
@@ -1285,7 +1285,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 	// Ping Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testPingSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -1348,7 +1348,7 @@ void testPingSuccess(String clientType) {
 	// Tool Structured Output Schema Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputValidationSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -1593,7 +1593,7 @@ void testStructuredOutputValidationFailure(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputMissingStructuredContent(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -1644,7 +1644,7 @@ void testStructuredOutputMissingStructuredContent(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputRuntimeToolAddition(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
index fd05b593b..d2b9d14d0 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletSseIntegrationTests.java
@@ -6,6 +6,7 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
@@ -21,6 +22,7 @@
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -37,6 +39,10 @@ class HttpServletSseIntegrationTests extends AbstractMcpClientServerIntegrationT
 
 	private Tomcat tomcat;
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"));
+	}
+
 	@BeforeEach
 	public void before() {
 		// Create and configure the transport provider
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
index 223c78a94..81423e0c5 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStreamableIntegrationTests.java
@@ -6,6 +6,7 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import io.modelcontextprotocol.client.McpClient;
 import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
@@ -21,6 +22,7 @@
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -35,6 +37,10 @@ class HttpServletStreamableIntegrationTests extends AbstractMcpClientServerInteg
 
 	private Tomcat tomcat;
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"));
+	}
+
 	@BeforeEach
 	public void before() {
 		// Create and configure the transport provider
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
index f580b59e8..eb8abb90c 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java
@@ -6,10 +6,13 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
+
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -45,6 +48,10 @@ class WebFluxSseIntegrationTests extends AbstractMcpClientServerIntegrationTests
 	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r) -> McpTransportContext
 		.create(Map.of("important", "value"));
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"), Arguments.of("webflux"));
+	}
+
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
index a00e24b55..96a786a9e 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStatelessIntegrationTests.java
@@ -5,10 +5,13 @@
 package io.modelcontextprotocol;
 
 import java.time.Duration;
+import java.util.stream.Stream;
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
+
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -35,6 +38,10 @@ class WebFluxStatelessIntegrationTests extends AbstractStatelessIntegrationTests
 
 	private WebFluxStatelessServerTransport mcpStreamableServerTransport;
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"), Arguments.of("webflux"));
+	}
+
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 		clientBuilders
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
index e4bcef829..5ab651931 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableIntegrationTests.java
@@ -6,10 +6,13 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
+
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -43,6 +46,10 @@ class WebFluxStreamableIntegrationTests extends AbstractMcpClientServerIntegrati
 	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = (r) -> McpTransportContext
 		.create(Map.of("important", "value"));
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"), Arguments.of("webflux"));
+	}
+
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
index 3dacb62d8..1150e47f5 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
@@ -31,7 +31,7 @@
 import org.springframework.http.codec.ServerSentEvent;
 import org.springframework.web.reactive.function.client.WebClient;
 
-import static io.modelcontextprotocol.utils.McpJsonMapperUtils.JSON_MAPPER;
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
index ae1f4f4d1..36aaa27fb 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableAsyncServerTransportTests.java
@@ -8,6 +8,7 @@
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.startup.Tomcat;
 import org.junit.jupiter.api.Timeout;
+
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
@@ -21,7 +22,7 @@
 import reactor.netty.DisposableServer;
 
 /**
- * Tests for {@link McpAsyncServer} using {@link WebFluxSseServerTransportProvider}.
+ * Tests for {@link McpAsyncServer} using {@link WebMvcSseServerTransportProvider}.
  *
  * @author Christian Tzolov
  */
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
index c8c24b8a7..2f75551eb 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMcpStreamableSyncServerTransportTests.java
@@ -21,7 +21,7 @@
 import reactor.netty.DisposableServer;
 
 /**
- * Tests for {@link McpAsyncServer} using {@link WebFluxSseServerTransportProvider}.
+ * Tests for {@link McpAsyncServer} using {@link WebMvcSseServerTransportProvider}.
  *
  * @author Christian Tzolov
  */
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
index e780b8e51..045f9b3dd 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcSseIntegrationTests.java
@@ -7,12 +7,15 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
+
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -43,6 +46,10 @@ class WebMvcSseIntegrationTests extends AbstractMcpClientServerIntegrationTests
 	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = r -> McpTransportContext
 		.create(Map.of("important", "value"));
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"), Arguments.of("webflux"));
+	}
+
 	@Override
 	protected void prepareClients(int port, String mcpEndpoint) {
 
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
index 9633dfbd1..8c7b0a85e 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStatelessIntegrationTests.java
@@ -6,12 +6,15 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import java.time.Duration;
+import java.util.stream.Stream;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
+
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -37,6 +40,10 @@ class WebMvcStatelessIntegrationTests extends AbstractStatelessIntegrationTests
 
 	private WebMvcStatelessServerTransport mcpServerTransport;
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"), Arguments.of("webflux"));
+	}
+
 	@Configuration
 	@EnableWebMvc
 	static class TestConfig {
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
index abdd82967..cb7b4a2a0 100644
--- a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/WebMvcStreamableIntegrationTests.java
@@ -7,12 +7,15 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import org.apache.catalina.LifecycleException;
 import org.apache.catalina.LifecycleState;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Timeout;
+import org.junit.jupiter.params.provider.Arguments;
+
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -43,6 +46,10 @@ class WebMvcStreamableIntegrationTests extends AbstractMcpClientServerIntegratio
 	static McpTransportContextExtractor TEST_CONTEXT_EXTRACTOR = r -> McpTransportContext
 		.create(Map.of("important", "value"));
 
+	static Stream clientsForTesting() {
+		return Stream.of(Arguments.of("httpclient"), Arguments.of("webflux"));
+	}
+
 	@Configuration
 	@EnableWebMvc
 	static class TestConfig {
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index a36d9006a..84bd271a5 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -50,11 +50,12 @@
 import io.modelcontextprotocol.util.Utils;
 import net.javacrumbs.jsonunit.core.Option;
 import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
-import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -74,7 +75,7 @@ public abstract class AbstractMcpClientServerIntegrationTests {
 	abstract protected McpServer.SyncSpecification prepareSyncServerBuilder();
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void simple(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -100,7 +101,7 @@ void simple(String clientType) {
 	// Sampling Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -136,7 +137,7 @@ void testCreateMessageWithoutSamplingCapabilities(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -205,7 +206,7 @@ void testCreateMessageSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws InterruptedException {
 
 		// Client
@@ -285,7 +286,7 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateMessageWithRequestTimeoutFail(String clientType) throws InterruptedException {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -351,7 +352,7 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 	// Elicitation Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -383,7 +384,7 @@ void testCreateElicitationWithoutElicitationCapabilities(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -440,7 +441,7 @@ void testCreateElicitationSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -501,7 +502,7 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 
 		var latch = new CountDownLatch(1);
@@ -572,7 +573,7 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 	// Roots Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testRootsSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -620,7 +621,7 @@ void testRootsSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testRootsWithoutCapability(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -659,7 +660,7 @@ void testRootsWithoutCapability(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testRootsNotificationWithEmptyRootsList(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -689,7 +690,7 @@ void testRootsNotificationWithEmptyRootsList(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testRootsWithMultipleHandlers(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -723,7 +724,7 @@ void testRootsWithMultipleHandlers(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testRootsServerCloseWithActiveSubscription(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -758,7 +759,7 @@ void testRootsServerCloseWithActiveSubscription(String clientType) {
 	// Tools Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testToolCallSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -809,7 +810,7 @@ void testToolCallSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -847,7 +848,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -904,7 +905,7 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testToolListChangeHandlingSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -997,7 +998,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testInitialize(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -1018,7 +1019,7 @@ void testInitialize(String clientType) {
 	// Logging Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testLoggingNotification(String clientType) throws InterruptedException {
 		int expectedNotificationsCount = 3;
 		CountDownLatch latch = new CountDownLatch(expectedNotificationsCount);
@@ -1131,7 +1132,7 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 	// Progress Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testProgressNotification(String clientType) throws InterruptedException {
 		int expectedNotificationsCount = 4; // 3 notifications + 1 for another progress
 											// token
@@ -1237,7 +1238,7 @@ void testProgressNotification(String clientType) throws InterruptedException {
 	// Completion Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : Completion call")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -1288,7 +1289,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 	// Ping Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testPingSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -1351,7 +1352,7 @@ void testPingSuccess(String clientType) {
 	// Tool Structured Output Schema Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputValidationSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -1596,7 +1597,7 @@ void testStructuredOutputValidationFailure(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputMissingStructuredContent(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -1647,7 +1648,7 @@ void testStructuredOutputMissingStructuredContent(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputRuntimeToolAddition(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
index 705535e93..240732ebe 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractStatelessIntegrationTests.java
@@ -28,10 +28,11 @@
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import net.javacrumbs.jsonunit.core.Option;
 import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.jupiter.params.provider.ValueSource;
 import reactor.core.publisher.Mono;
 
-import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.assertThatJson;
 import static net.javacrumbs.jsonunit.assertj.JsonAssertions.json;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -49,7 +50,7 @@ public abstract class AbstractStatelessIntegrationTests {
 	abstract protected StatelessSyncSpecification prepareSyncServerBuilder();
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void simple(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -76,7 +77,7 @@ void simple(String clientType) {
 	// Tools Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testToolCallSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -126,7 +127,7 @@ void testToolCallSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -164,7 +165,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testToolListChangeHandlingSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -246,7 +247,7 @@ void testToolListChangeHandlingSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testInitialize(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -267,7 +268,7 @@ void testInitialize(String clientType) {
 	// Tool Structured Output Schema Tests
 	// ---------------------------------------
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputValidationSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -342,7 +343,7 @@ void testStructuredOutputValidationSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputOfObjectArrayValidationSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -402,7 +403,7 @@ void testStructuredOutputOfObjectArrayValidationSuccess(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputWithInHandlerError(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -460,7 +461,7 @@ void testStructuredOutputWithInHandlerError(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputValidationFailure(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -516,7 +517,7 @@ void testStructuredOutputValidationFailure(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputMissingStructuredContent(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
@@ -567,7 +568,7 @@ void testStructuredOutputMissingStructuredContent(String clientType) {
 	}
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
-	@ValueSource(strings = { "httpclient", "webflux" })
+	@MethodSource("clientsForTesting")
 	void testStructuredOutputRuntimeToolAddition(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 8a0b3e0d9..e1b051204 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.client;
 
-import static io.modelcontextprotocol.utils.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -23,7 +22,6 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
-import io.modelcontextprotocol.json.McpJsonMapper;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
@@ -54,6 +52,8 @@
 import reactor.core.publisher.Sinks;
 import reactor.test.StepVerifier;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
+
 /**
  * Test suite for the {@link McpAsyncClient} that can be used with different
  * {@link McpTransport} implementations.
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index b0701911a..ed7f2c3ce 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -26,7 +26,7 @@
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
-import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index d804de43b..d7b1dab2a 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -4,7 +4,6 @@
 
 package io.modelcontextprotocol.server;
 
-import static io.modelcontextprotocol.utils.ToolsUtils.EMPTY_JSON_SCHEMA;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -15,6 +14,8 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
+
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java b/mcp-test/src/main/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
similarity index 84%
rename from mcp-test/src/main/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
rename to mcp-test/src/main/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
index e9ec8900c..723965519 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/utils/McpJsonMapperUtils.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/util/McpJsonMapperUtils.java
@@ -1,4 +1,4 @@
-package io.modelcontextprotocol.utils;
+package io.modelcontextprotocol.util;
 
 import io.modelcontextprotocol.json.McpJsonMapper;
 
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/utils/ToolsUtils.java b/mcp-test/src/main/java/io/modelcontextprotocol/util/ToolsUtils.java
similarity index 88%
rename from mcp-test/src/main/java/io/modelcontextprotocol/utils/ToolsUtils.java
rename to mcp-test/src/main/java/io/modelcontextprotocol/util/ToolsUtils.java
index ec603aac1..ce8755223 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/utils/ToolsUtils.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/util/ToolsUtils.java
@@ -1,4 +1,4 @@
-package io.modelcontextprotocol.utils;
+package io.modelcontextprotocol.util;
 
 import io.modelcontextprotocol.spec.McpSchema;
 

From 8159bcbb05362611aa2cf63ebaf79456d7999c7e Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Thu, 18 Sep 2025 08:57:10 +0200
Subject: [PATCH 075/125] feat: add MCP protocol version 2025-06-18 support for
 streamable-http and stateless transports (#558)

- Set MCP_2025_06_18 as upper supported protocol version for streamable-http and stateless transport
- Update LATEST_PROTOCOL_VERSION constant to reflect new upper bound
- Update test expectations for new protocol version usage

Signed-off-by: Christian Tzolov 
---
 .../client/transport/HttpClientStreamableHttpTransport.java  | 5 +++--
 .../HttpServletStreamableServerTransportProvider.java        | 3 ++-
 .../main/java/io/modelcontextprotocol/spec/McpSchema.java    | 2 +-
 .../spec/McpStatelessServerTransport.java                    | 2 +-
 .../transport/HttpClientStreamableHttpTransportTest.java     | 4 ++--
 .../client/transport/WebClientStreamableHttpTransport.java   | 5 +++--
 .../transport/WebFluxStreamableServerTransportProvider.java  | 3 ++-
 .../transport/WebMvcStreamableServerTransportProvider.java   | 3 ++-
 8 files changed, 16 insertions(+), 11 deletions(-)

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 c73515938..fb8813542 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
@@ -77,7 +77,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(HttpClientStreamableHttpTransport.class);
 
-	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_03_26;
+	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_06_18;
 
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
@@ -140,7 +140,8 @@ private HttpClientStreamableHttpTransport(McpJsonMapper jsonMapper, HttpClient h
 
 	@Override
 	public List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26,
+				ProtocolVersions.MCP_2025_06_18);
 	}
 
 	public static Builder builder(String baseUri) {
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
index 137015876..34671c105 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletStreamableServerTransportProvider.java
@@ -156,7 +156,8 @@ private HttpServletStreamableServerTransportProvider(McpJsonMapper jsonMapper, S
 
 	@Override
 	public List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26,
+				ProtocolVersions.MCP_2025_06_18);
 	}
 
 	@Override
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 32b2bae36..40c23d2fb 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -44,7 +44,7 @@ private McpSchema() {
 	}
 
 	@Deprecated
-	public static final String LATEST_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_03_26;
+	public static final String LATEST_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_06_18;
 
 	public static final String JSONRPC_VERSION = "2.0";
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
index c1234b130..d1c2e5206 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStatelessServerTransport.java
@@ -29,7 +29,7 @@ default void close() {
 	Mono closeGracefully();
 
 	default List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2025_03_26);
+		return List.of(ProtocolVersions.MCP_2025_03_26, ProtocolVersions.MCP_2025_06_18);
 	}
 
 }
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index 234874834..0a09766d1 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -90,7 +90,7 @@ void testRequestCustomizer() throws URISyntaxException {
 
 			// Verify the customizer was called
 			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
 					eq(context));
 		});
 	}
@@ -120,7 +120,7 @@ void testAsyncRequestCustomizer() throws URISyntaxException {
 
 			// Verify the customizer was called
 			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
 					eq(context));
 		});
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 154eb4703..24f9e1d0b 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -75,7 +75,7 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(WebClientStreamableHttpTransport.class);
 
-	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_03_26;
+	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_06_18;
 
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
@@ -116,7 +116,8 @@ private WebClientStreamableHttpTransport(McpJsonMapper jsonMapper, WebClient.Bui
 
 	@Override
 	public List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26,
+				ProtocolVersions.MCP_2025_06_18);
 	}
 
 	/**
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index b6cc20864..144a3ce02 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -97,7 +97,8 @@ private WebFluxStreamableServerTransportProvider(McpJsonMapper jsonMapper, Strin
 
 	@Override
 	public List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26,
+				ProtocolVersions.MCP_2025_06_18);
 	}
 
 	@Override
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index 9bb9bfa86..d85046a67 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -143,7 +143,8 @@ private WebMvcStreamableServerTransportProvider(McpJsonMapper jsonMapper, String
 
 	@Override
 	public List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26);
+		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26,
+				ProtocolVersions.MCP_2025_06_18);
 	}
 
 	@Override

From 3d86539452d4dca8b5fb8def27f97a6e479cd8f6 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Thu, 18 Sep 2025 16:46:40 +0200
Subject: [PATCH 076/125] fix(mcp): skip source/javadoc generation for
 aggregator module (#559)

The mcp module packages dependencies but has no sources, causing
Maven release failures. Skip source and javadoc JAR generation
to fix deployment errors.

Signed-off-by: Christian Tzolov 
---
 mcp/pom.xml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/mcp/pom.xml b/mcp/pom.xml
index 438c7535c..29acb2844 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -61,6 +61,24 @@
 					
 				
 			
+
+			
+			
+				org.apache.maven.plugins
+				maven-source-plugin
+				
+					true
+				
+			
+
+			
+			
+				org.apache.maven.plugins
+				maven-javadoc-plugin
+				
+					true
+				
+			
 		
 	
 

From 7525a9969360ddba9bb599cff52842ab829c5f79 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 18 Sep 2025 18:46:29 +0200
Subject: [PATCH 077/125] simplify the mcp module pom

Signed-off-by: Christian Tzolov 
---
 mcp/pom.xml | 84 ++++++++---------------------------------------------
 1 file changed, 12 insertions(+), 72 deletions(-)

diff --git a/mcp/pom.xml b/mcp/pom.xml
index 29acb2844..987c8b561 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -20,79 +20,19 @@
 		git@github.com/modelcontextprotocol/java-sdk.git
 	
 
-	
-		
-			
-				biz.aQute.bnd
-				bnd-maven-plugin
-				${bnd-maven-plugin.version}
-				
-					
-						bnd-process
-						
-							bnd-process
-						
-						
-							
-							
-						
-					
-				
-			
-
-			
-				org.apache.maven.plugins
-				maven-jar-plugin
-				
-					
-						${project.build.outputDirectory}/META-INF/MANIFEST.MF
-					
-				
-			
-
-			
-			
-				org.apache.maven.plugins
-				maven-source-plugin
-				
-					true
-				
-			
-
-			
-			
-				org.apache.maven.plugins
-				maven-javadoc-plugin
-				
-					true
-				
-			
-		
-	
-
 	
-        
-            io.modelcontextprotocol.sdk
-            mcp-json-jackson2
-            0.13.0-SNAPSHOT
-        
-        
-            io.modelcontextprotocol.sdk
-            mcp-core
-            0.13.0-SNAPSHOT
-        
+
+		
+			io.modelcontextprotocol.sdk
+			mcp-json-jackson2
+			0.13.0-SNAPSHOT
+		
+
+		
+			io.modelcontextprotocol.sdk
+			mcp-core
+			0.13.0-SNAPSHOT
+		
 	
 
 

From a0afdcd493fcd3add9dd4cb75c4a9304e8461f95 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 18 Sep 2025 19:28:56 +0200
Subject: [PATCH 078/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       |  2 +-
 mcp-core/pom.xml                      |  6 +++---
 mcp-json-jackson2/pom.xml             |  4 ++--
 mcp-json/pom.xml                      |  2 +-
 mcp-spring/mcp-spring-webflux/pom.xml |  8 ++++----
 mcp-spring/mcp-spring-webmvc/pom.xml  | 10 +++++-----
 mcp-test/pom.xml                      |  4 ++--
 mcp/pom.xml                           |  6 +++---
 pom.xml                               |  2 +-
 9 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index daa539011..6b1027a21 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.13.0-SNAPSHOT
+        0.14.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-core/pom.xml b/mcp-core/pom.xml
index 52d5bf58a..8637303fe 100644
--- a/mcp-core/pom.xml
+++ b/mcp-core/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.13.0-SNAPSHOT
+		0.14.0-SNAPSHOT
 	
 	mcp-core
 	jar
@@ -68,7 +68,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.13.0-SNAPSHOT
+            0.14.0-SNAPSHOT
         
 
 		
@@ -101,7 +101,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.13.0-SNAPSHOT
+            0.14.0-SNAPSHOT
             test
         
 
diff --git a/mcp-json-jackson2/pom.xml b/mcp-json-jackson2/pom.xml
index 25159a9fe..b3d0a16de 100644
--- a/mcp-json-jackson2/pom.xml
+++ b/mcp-json-jackson2/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.13.0-SNAPSHOT
+		0.14.0-SNAPSHOT
 	
 	mcp-json-jackson2
 	jar
@@ -37,7 +37,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.13.0-SNAPSHOT
+            0.14.0-SNAPSHOT
         
         
             com.fasterxml.jackson.core
diff --git a/mcp-json/pom.xml b/mcp-json/pom.xml
index 037ef2ac4..ebbc90142 100644
--- a/mcp-json/pom.xml
+++ b/mcp-json/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.13.0-SNAPSHOT
+		0.14.0-SNAPSHOT
 	
 	mcp-json
 	jar
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index eda38881a..5a96e609d 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.13.0-SNAPSHOT
+		0.14.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,19 +25,19 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.13.0-SNAPSHOT
+            0.14.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 8c698487d..e59c94c22 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.13.0-SNAPSHOT
+		0.14.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,13 +25,13 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.13.0-SNAPSHOT
+            0.14.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 		
 
 		
@@ -43,14 +43,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 			test
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 5b77d0acb..cbaabdada 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.13.0-SNAPSHOT
+		0.14.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 987c8b561..492bd447d 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.13.0-SNAPSHOT
+		0.14.0-SNAPSHOT
 	
 	mcp
 	jar
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-json-jackson2
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-core
-			0.13.0-SNAPSHOT
+			0.14.0-SNAPSHOT
 		
 	
 
diff --git a/pom.xml b/pom.xml
index 388fc6d9b..a5fd98b7f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.13.0-SNAPSHOT
+	0.14.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From d327fff6f79bff83f571a69a5357a57a4d707a12 Mon Sep 17 00:00:00 2001
From: Sergio del Amo 
Date: Mon, 22 Sep 2025 16:43:44 +0200
Subject: [PATCH 079/125] fix: handle resource not found according to spec
 (#567)

see: https://modelcontextprotocol.io/specification/2025-06-18/server/resources#error-handling

Resource not found should send a JSON RPC response such as:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}
```

This PR also changes some instances where a `McpError` was thrown instead of being passed in the reactive chain with `Mono.error`

functional style
---
 .../server/McpAsyncServer.java                | 31 ++++++++++---------
 .../server/McpStatelessAsyncServer.java       | 30 +++++++++---------
 .../modelcontextprotocol/spec/McpError.java   | 11 +++++++
 .../modelcontextprotocol/spec/McpSchema.java  |  5 +++
 .../spec/McpErrorTest.java                    | 21 +++++++++++++
 5 files changed, 68 insertions(+), 30 deletions(-)
 create mode 100644 mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index 38a16bd7e..bedae1590 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -48,6 +48,8 @@
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
+import static io.modelcontextprotocol.spec.McpError.RESOURCE_NOT_FOUND;
+
 /**
  * The Model Context Protocol (MCP) server implementation that provides asynchronous
  * communication using Project Reactor's Mono and Flux types.
@@ -638,24 +640,23 @@ private List getResourceTemplates() {
 	}
 
 	private McpRequestHandler resourcesReadRequestHandler() {
-		return (exchange, params) -> {
-			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params,
-					new TypeRef() {
-					});
+		return (ex, params) -> {
+			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params, new TypeRef<>() {
+			});
 			var resourceUri = resourceRequest.uri();
-
-			McpServerFeatures.AsyncResourceSpecification specification = this.resources.values()
-				.stream()
-				.filter(resourceSpecification -> this.uriTemplateManagerFactory
-					.create(resourceSpecification.resource().uri())
-					.matches(resourceUri))
-				.findFirst()
-				.orElseThrow(() -> new McpError("Resource not found: " + resourceUri));
-
-			return Mono.defer(() -> specification.readHandler().apply(exchange, resourceRequest));
+			return asyncResourceSpecification(resourceUri)
+				.map(spec -> Mono.defer(() -> spec.readHandler().apply(ex, resourceRequest)))
+				.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
 		};
 	}
 
+	private Optional asyncResourceSpecification(String uri) {
+		return resources.values()
+			.stream()
+			.filter(spec -> uriTemplateManagerFactory.create(spec.resource().uri()).matches(uri))
+			.findFirst();
+	}
+
 	// ---------------------------------------
 	// Prompt Management
 	// ---------------------------------------
@@ -846,7 +847,7 @@ private McpRequestHandler completionCompleteRequestHan
 			if (type.equals("ref/resource") && request.ref() instanceof McpSchema.ResourceReference resourceReference) {
 				McpServerFeatures.AsyncResourceSpecification resourceSpec = this.resources.get(resourceReference.uri());
 				if (resourceSpec == null) {
-					return Mono.error(new McpError("Resource not found: " + resourceReference.uri()));
+					return Mono.error(RESOURCE_NOT_FOUND.apply(resourceReference.uri()));
 				}
 				if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
 					.getVariableNames()
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 8f79d8c68..1dde58d69 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -33,6 +33,8 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.BiFunction;
 
+import static io.modelcontextprotocol.spec.McpError.RESOURCE_NOT_FOUND;
+
 /**
  * A stateless MCP server implementation for use with Streamable HTTP transport types. It
  * allows simple horizontal scalability since it does not maintain a session and does not
@@ -478,23 +480,21 @@ private List getResourceTemplates() {
 
 	private McpStatelessRequestHandler resourcesReadRequestHandler() {
 		return (ctx, params) -> {
-			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params,
-					new TypeRef() {
-					});
+			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params, new TypeRef<>() {
+			});
 			var resourceUri = resourceRequest.uri();
-
-			McpStatelessServerFeatures.AsyncResourceSpecification specification = this.resources.values()
-				.stream()
-				.filter(resourceSpecification -> this.uriTemplateManagerFactory
-					.create(resourceSpecification.resource().uri())
-					.matches(resourceUri))
-				.findFirst()
-				.orElseThrow(() -> new McpError("Resource not found: " + resourceUri));
-
-			return specification.readHandler().apply(ctx, resourceRequest);
+			return asyncResourceSpecification(resourceUri).map(spec -> spec.readHandler().apply(ctx, resourceRequest))
+				.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
 		};
 	}
 
+	private Optional asyncResourceSpecification(String uri) {
+		return resources.values()
+			.stream()
+			.filter(spec -> uriTemplateManagerFactory.create(spec.resource().uri()).matches(uri))
+			.findFirst();
+	}
+
 	// ---------------------------------------
 	// Prompt Management
 	// ---------------------------------------
@@ -612,10 +612,10 @@ private McpStatelessRequestHandler completionCompleteR
 			}
 
 			if (type.equals("ref/resource") && request.ref() instanceof McpSchema.ResourceReference resourceReference) {
-				McpStatelessServerFeatures.AsyncResourceSpecification resourceSpec = this.resources
+				McpStatelessServerFeatures.AsyncResourceSpecification resourceSpec = resources
 					.get(resourceReference.uri());
 				if (resourceSpec == null) {
-					return Mono.error(new McpError("Resource not found: " + resourceReference.uri()));
+					return Mono.error(RESOURCE_NOT_FOUND.apply(resourceReference.uri()));
 				}
 				if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
 					.getVariableNames()
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
index 6172d8637..4f717306a 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
@@ -7,8 +7,19 @@
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse.JSONRPCError;
 import io.modelcontextprotocol.util.Assert;
 
+import java.util.Map;
+import java.util.function.Function;
+
 public class McpError extends RuntimeException {
 
+	/**
+	 * Resource
+	 * Error Handling
+	 */
+	public static final Function RESOURCE_NOT_FOUND = resourceUri -> new McpError(new JSONRPCError(
+			McpSchema.ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found", Map.of("uri", resourceUri)));
+
 	private JSONRPCError jsonRpcError;
 
 	public McpError(JSONRPCError jsonRpcError) {
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 40c23d2fb..de72968e0 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -143,6 +143,11 @@ public static final class ErrorCodes {
 		 */
 		public static final int INTERNAL_ERROR = -32603;
 
+		/**
+		 * Resource not found.
+		 */
+		public static final int RESOURCE_NOT_FOUND = -32002;
+
 	}
 
 	public sealed interface Request
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java
new file mode 100644
index 000000000..84d650ab3
--- /dev/null
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java
@@ -0,0 +1,21 @@
+package io.modelcontextprotocol.spec;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class McpErrorTest {
+
+	@Test
+	void testNotFound() {
+		String uri = "file:///nonexistent.txt";
+		McpError mcpError = McpError.RESOURCE_NOT_FOUND.apply(uri);
+		assertNotNull(mcpError.getJsonRpcError());
+		assertEquals(-32002, mcpError.getJsonRpcError().code());
+		assertEquals("Resource not found", mcpError.getJsonRpcError().message());
+		assertEquals(Map.of("uri", uri), mcpError.getJsonRpcError().data());
+	}
+
+}
\ No newline at end of file

From a90b922be92b4b5311206d848c482b6f3698dd44 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Mon, 22 Sep 2025 17:07:19 +0200
Subject: [PATCH 080/125] feat: add optional lastModified field to Annotations
 record with backward compatibility (#568)

Resolves #565

Signed-off-by: Christian Tzolov 
---
 .../main/java/io/modelcontextprotocol/spec/McpSchema.java | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index de72968e0..44da6dd39 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -653,7 +653,13 @@ public interface Annotated {
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record Annotations( // @formatter:off
 		@JsonProperty("audience") List audience,
-		@JsonProperty("priority") Double priority) { // @formatter:on
+		@JsonProperty("priority") Double priority,
+		@JsonProperty("lastModified") String lastModified
+		) { // @formatter:on
+
+		public Annotations(List audience, Double priority) {
+			this(audience, priority, null);
+		}
 	}
 
 	/**

From 7f16cd0b9dc72f5adc3358a903bebb0f909dda3e Mon Sep 17 00:00:00 2001
From: Liujunjie <42363259+JunJieLiu51520@users.noreply.github.com>
Date: Mon, 22 Sep 2025 23:18:53 +0800
Subject: [PATCH 081/125] fix: typo MCP_SESSION_ID, keep consistent style with
 other identifiers (#564)

---
 .../src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
index 65b80957c..370b47070 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
@@ -14,7 +14,7 @@ public interface HttpHeaders {
 	/**
 	 * Identifies individual MCP sessions.
 	 */
-	String MCP_SESSION_ID = "mcp-session-id";
+	String MCP_SESSION_ID = "Mcp-Session-Id";
 
 	/**
 	 * Identifies events within an SSE Stream.

From ff98e294f50e9d8d82c639b0276f57dafde72608 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 25 Sep 2025 16:32:58 +0200
Subject: [PATCH 082/125] refactor: Improve resource template support (#576)

- Provide separation of concerns between static resources and parameterized resource templates.
- Add AsyncResourceTemplateSpecification and SyncResourceTemplateSpecification for both McpServerFeatures and McpStatelessServerFeatures
- Change resource template storage from List to Map to acomodate the resource read handler.
- Add runtime management methods: addResourceTemplate(), removeResourceTemplate(), listResourceTemplates()
- Improve error handling by using IllegalArgumentException/IllegalStateException instead of McpError
- Add new interfaces (Meta, Identifier) and reorganize schema hierarchy
- Enhance completion request validation with better error messages
- Add ResourceTemplate.Builder for easier template construction
- Update all server implementations (Async, Sync, Stateless) consistently
- Add type-safe constants for reference types (PromptReference.TYPE, ResourceReference.TYPE)
- Add tests for new resource template management functionality
- Clean up imports and remove unused dependencies

Co-authored-by: Pascal Vantrepote 

Signed-off-by: Christian Tzolov 
---
 .../server/McpAsyncServer.java                | 266 ++++++++++++----
 .../server/McpServer.java                     | 151 +++++----
 .../server/McpServerFeatures.java             |  92 +++++-
 .../server/McpStatelessAsyncServer.java       | 255 +++++++++++----
 .../server/McpStatelessServerFeatures.java    | 111 +++++--
 .../server/McpStatelessSyncServer.java        |  36 +++
 .../server/McpSyncServer.java                 |  45 ++-
 .../modelcontextprotocol/spec/McpError.java   |   9 +
 .../modelcontextprotocol/spec/McpSchema.java  | 172 ++++++----
 .../util/DefaultMcpUriTemplateManager.java    |  10 +-
 .../server/AbstractMcpAsyncServerTests.java   | 200 +++++++++++-
 ...stractMcpClientServerIntegrationTests.java |   7 +-
 .../server/AbstractMcpSyncServerTests.java    | 195 +++++++++++-
 .../HttpServletStatelessIntegrationTests.java |   6 +-
 .../server/McpCompletionTests.java            |  20 +-
 .../ResourceTemplateManagementTests.java      | 299 ++++++++++++++++++
 .../spec/PromptReferenceEqualsTest.java       |  37 ++-
 ...stractMcpClientServerIntegrationTests.java |   7 +-
 .../server/AbstractMcpAsyncServerTests.java   | 198 +++++++++++-
 .../server/AbstractMcpSyncServerTests.java    | 227 +++++++++++--
 20 files changed, 1957 insertions(+), 386 deletions(-)
 create mode 100644 mcp-core/src/test/java/io/modelcontextprotocol/server/ResourceTemplateManagementTests.java

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index bedae1590..c07fdf2af 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -5,7 +5,6 @@
 package io.modelcontextprotocol.server;
 
 import java.time.Duration;
-import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -15,24 +14,21 @@
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.BiFunction;
 
-import io.modelcontextprotocol.spec.DefaultMcpStreamableServerSessionFactory;
-import io.modelcontextprotocol.spec.McpServerTransportProviderBase;
-import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
-
 import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
+import io.modelcontextprotocol.spec.DefaultMcpStreamableServerSessionFactory;
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult.CompleteCompletion;
+import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse;
 import io.modelcontextprotocol.spec.McpSchema.LoggingLevel;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
-import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
+import io.modelcontextprotocol.spec.McpSchema.ResourceReference;
 import io.modelcontextprotocol.spec.McpSchema.SetLevelRequest;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerSession;
@@ -110,10 +106,10 @@ public class McpAsyncServer {
 
 	private final CopyOnWriteArrayList tools = new CopyOnWriteArrayList<>();
 
-	private final CopyOnWriteArrayList resourceTemplates = new CopyOnWriteArrayList<>();
-
 	private final ConcurrentHashMap resources = new ConcurrentHashMap<>();
 
+	private final ConcurrentHashMap resourceTemplates = new ConcurrentHashMap<>();
+
 	private final ConcurrentHashMap prompts = new ConcurrentHashMap<>();
 
 	// FIXME: this field is deprecated and should be remvoed together with the
@@ -143,7 +139,7 @@ public class McpAsyncServer {
 		this.instructions = features.instructions();
 		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
 		this.resources.putAll(features.resources());
-		this.resourceTemplates.addAll(features.resourceTemplates());
+		this.resourceTemplates.putAll(features.resourceTemplates());
 		this.prompts.putAll(features.prompts());
 		this.completions.putAll(features.completions());
 		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
@@ -168,7 +164,7 @@ public class McpAsyncServer {
 		this.instructions = features.instructions();
 		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
 		this.resources.putAll(features.resources());
-		this.resourceTemplates.addAll(features.resourceTemplates());
+		this.resourceTemplates.putAll(features.resourceTemplates());
 		this.prompts.putAll(features.prompts());
 		this.completions.putAll(features.completions());
 		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
@@ -541,19 +537,22 @@ private McpRequestHandler toolsCallRequestHandler() {
 	 */
 	public Mono addResource(McpServerFeatures.AsyncResourceSpecification resourceSpecification) {
 		if (resourceSpecification == null || resourceSpecification.resource() == null) {
-			return Mono.error(new McpError("Resource must not be null"));
+			return Mono.error(new IllegalArgumentException("Resource must not be null"));
 		}
 
 		if (this.serverCapabilities.resources() == null) {
-			return Mono.error(new McpError("Server must be configured with resource capabilities"));
+			return Mono.error(new IllegalStateException(
+					"Server must be configured with resource capabilities to allow adding resources"));
 		}
 
 		return Mono.defer(() -> {
-			if (this.resources.putIfAbsent(resourceSpecification.resource().uri(), resourceSpecification) != null) {
-				return Mono.error(new McpError(
-						"Resource with URI '" + resourceSpecification.resource().uri() + "' already exists"));
+			var previous = this.resources.put(resourceSpecification.resource().uri(), resourceSpecification);
+			if (previous != null) {
+				logger.warn("Replace existing Resource with URI '{}'", resourceSpecification.resource().uri());
+			}
+			else {
+				logger.debug("Added resource handler: {}", resourceSpecification.resource().uri());
 			}
-			logger.debug("Added resource handler: {}", resourceSpecification.resource().uri());
 			if (this.serverCapabilities.resources().listChanged()) {
 				return notifyResourcesListChanged();
 			}
@@ -561,6 +560,14 @@ public Mono addResource(McpServerFeatures.AsyncResourceSpecification resou
 		});
 	}
 
+	/**
+	 * List all registered resources.
+	 * @return A Flux stream of all registered resources
+	 */
+	public Flux listResources() {
+		return Flux.fromIterable(this.resources.values()).map(McpServerFeatures.AsyncResourceSpecification::resource);
+	}
+
 	/**
 	 * Remove a resource handler at runtime.
 	 * @param resourceUri The URI of the resource handler to remove
@@ -568,10 +575,11 @@ public Mono addResource(McpServerFeatures.AsyncResourceSpecification resou
 	 */
 	public Mono removeResource(String resourceUri) {
 		if (resourceUri == null) {
-			return Mono.error(new McpError("Resource URI must not be null"));
+			return Mono.error(new IllegalArgumentException("Resource URI must not be null"));
 		}
 		if (this.serverCapabilities.resources() == null) {
-			return Mono.error(new McpError("Server must be configured with resource capabilities"));
+			return Mono.error(new IllegalStateException(
+					"Server must be configured with resource capabilities to allow removing resources"));
 		}
 
 		return Mono.defer(() -> {
@@ -583,7 +591,74 @@ public Mono removeResource(String resourceUri) {
 				}
 				return Mono.empty();
 			}
-			return Mono.error(new McpError("Resource with URI '" + resourceUri + "' not found"));
+			else {
+				logger.warn("Ignore as a Resource with URI '{}' not found", resourceUri);
+			}
+			return Mono.empty();
+		});
+	}
+
+	/**
+	 * Add a new resource template at runtime.
+	 * @param resourceTemplateSpecification The resource template to add
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono addResourceTemplate(
+			McpServerFeatures.AsyncResourceTemplateSpecification resourceTemplateSpecification) {
+
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new IllegalStateException(
+					"Server must be configured with resource capabilities to allow adding resource templates"));
+		}
+
+		return Mono.defer(() -> {
+			var previous = this.resourceTemplates.put(resourceTemplateSpecification.resourceTemplate().uriTemplate(),
+					resourceTemplateSpecification);
+			if (previous != null) {
+				logger.warn("Replace existing Resource Template with URI '{}'",
+						resourceTemplateSpecification.resourceTemplate().uriTemplate());
+			}
+			else {
+				logger.debug("Added resource template handler: {}",
+						resourceTemplateSpecification.resourceTemplate().uriTemplate());
+			}
+			if (this.serverCapabilities.resources().listChanged()) {
+				return notifyResourcesListChanged();
+			}
+			return Mono.empty();
+		});
+	}
+
+	/**
+	 * List all registered resource templates.
+	 * @return A Flux stream of all registered resource templates
+	 */
+	public Flux listResourceTemplates() {
+		return Flux.fromIterable(this.resourceTemplates.values())
+			.map(McpServerFeatures.AsyncResourceTemplateSpecification::resourceTemplate);
+	}
+
+	/**
+	 * Remove a resource template at runtime.
+	 * @param uriTemplate The URI template of the resource template to remove
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono removeResourceTemplate(String uriTemplate) {
+
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new IllegalStateException(
+					"Server must be configured with resource capabilities to allow removing resource templates"));
+		}
+
+		return Mono.defer(() -> {
+			McpServerFeatures.AsyncResourceTemplateSpecification removed = this.resourceTemplates.remove(uriTemplate);
+			if (removed != null) {
+				logger.debug("Removed resource template: {}", uriTemplate);
+			}
+			else {
+				logger.warn("Ignore as a Resource Template with URI '{}' not found", uriTemplate);
+			}
+			return Mono.empty();
 		});
 	}
 
@@ -609,51 +684,55 @@ private McpRequestHandler resourcesListRequestHan
 			var resourceList = this.resources.values()
 				.stream()
 				.map(McpServerFeatures.AsyncResourceSpecification::resource)
-				.filter(resource -> !resource.uri().contains("{"))
 				.toList();
 			return Mono.just(new McpSchema.ListResourcesResult(resourceList, null));
 		};
 	}
 
 	private McpRequestHandler resourceTemplateListRequestHandler() {
-		return (exchange, params) -> Mono
-			.just(new McpSchema.ListResourceTemplatesResult(this.getResourceTemplates(), null));
-
-	}
-
-	private List getResourceTemplates() {
-		var list = new ArrayList<>(this.resourceTemplates);
-		List resourceTemplates = this.resources.keySet()
-			.stream()
-			.filter(uri -> uri.contains("{"))
-			.map(uri -> {
-				var resource = this.resources.get(uri).resource();
-				var template = new McpSchema.ResourceTemplate(resource.uri(), resource.name(), resource.title(),
-						resource.description(), resource.mimeType(), resource.annotations());
-				return template;
-			})
-			.toList();
-
-		list.addAll(resourceTemplates);
-
-		return list;
+		return (exchange, params) -> {
+			var resourceList = this.resourceTemplates.values()
+				.stream()
+				.map(McpServerFeatures.AsyncResourceTemplateSpecification::resourceTemplate)
+				.toList();
+			return Mono.just(new McpSchema.ListResourceTemplatesResult(resourceList, null));
+		};
 	}
 
 	private McpRequestHandler resourcesReadRequestHandler() {
 		return (ex, params) -> {
 			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params, new TypeRef<>() {
 			});
+
 			var resourceUri = resourceRequest.uri();
-			return asyncResourceSpecification(resourceUri)
-				.map(spec -> Mono.defer(() -> spec.readHandler().apply(ex, resourceRequest)))
-				.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
+
+			// First try to find a static resource specification
+			// Static resources have exact URIs
+			return this.findResourceSpecification(resourceUri)
+				.map(spec -> spec.readHandler().apply(ex, resourceRequest))
+				.orElseGet(() -> {
+					// If not found, try to find a dynamic resource specification
+					// Dynamic resources have URI templates
+					return this.findResourceTemplateSpecification(resourceUri)
+						.map(spec -> spec.readHandler().apply(ex, resourceRequest))
+						.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
+				});
 		};
 	}
 
-	private Optional asyncResourceSpecification(String uri) {
-		return resources.values()
+	private Optional findResourceSpecification(String uri) {
+		var result = this.resources.values()
 			.stream()
-			.filter(spec -> uriTemplateManagerFactory.create(spec.resource().uri()).matches(uri))
+			.filter(spec -> this.uriTemplateManagerFactory.create(spec.resource().uri()).matches(uri))
+			.findFirst();
+		return result;
+	}
+
+	private Optional findResourceTemplateSpecification(
+			String uri) {
+		return this.resourceTemplates.values()
+			.stream()
+			.filter(spec -> this.uriTemplateManagerFactory.create(spec.resourceTemplate().uriTemplate()).matches(uri))
 			.findFirst();
 	}
 
@@ -811,27 +890,38 @@ private McpRequestHandler setLoggerRequestHandler() {
 		};
 	}
 
+	private static final Mono EMPTY_COMPLETION_RESULT = Mono
+		.just(new McpSchema.CompleteResult(new CompleteCompletion(List.of(), 0, false)));
+
 	private McpRequestHandler completionCompleteRequestHandler() {
 		return (exchange, params) -> {
+
 			McpSchema.CompleteRequest request = parseCompletionParams(params);
 
 			if (request.ref() == null) {
-				return Mono.error(new McpError("ref must not be null"));
+				return Mono.error(
+						McpError.builder(ErrorCodes.INVALID_PARAMS).message("Completion ref must not be null").build());
 			}
 
 			if (request.ref().type() == null) {
-				return Mono.error(new McpError("type must not be null"));
+				return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+					.message("Completion ref type must not be null")
+					.build());
 			}
 
 			String type = request.ref().type();
 
 			String argumentName = request.argument().name();
 
-			// check if the referenced resource exists
-			if (type.equals("ref/prompt") && request.ref() instanceof McpSchema.PromptReference promptReference) {
+			// Check if valid a Prompt exists for this completion request
+			if (type.equals(PromptReference.TYPE)
+					&& request.ref() instanceof McpSchema.PromptReference promptReference) {
+
 				McpServerFeatures.AsyncPromptSpecification promptSpec = this.prompts.get(promptReference.name());
 				if (promptSpec == null) {
-					return Mono.error(new McpError("Prompt not found: " + promptReference.name()));
+					return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+						.message("Prompt not found: " + promptReference.name())
+						.build());
 				}
 				if (!promptSpec.prompt()
 					.arguments()
@@ -840,27 +930,67 @@ private McpRequestHandler completionCompleteRequestHan
 					.findFirst()
 					.isPresent()) {
 
-					return Mono.error(new McpError("Argument not found: " + argumentName));
+					logger.warn("Argument not found: {} in prompt: {}", argumentName, promptReference.name());
+
+					return EMPTY_COMPLETION_RESULT;
 				}
 			}
 
-			if (type.equals("ref/resource") && request.ref() instanceof McpSchema.ResourceReference resourceReference) {
-				McpServerFeatures.AsyncResourceSpecification resourceSpec = this.resources.get(resourceReference.uri());
-				if (resourceSpec == null) {
-					return Mono.error(RESOURCE_NOT_FOUND.apply(resourceReference.uri()));
-				}
-				if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
-					.getVariableNames()
-					.contains(argumentName)) {
-					return Mono.error(new McpError("Argument not found: " + argumentName));
+			// Check if valid Resource or ResourceTemplate exists for this completion
+			// request
+			if (type.equals(ResourceReference.TYPE)
+					&& request.ref() instanceof McpSchema.ResourceReference resourceReference) {
+
+				var uriTemplateManager = uriTemplateManagerFactory.create(resourceReference.uri());
+
+				if (!uriTemplateManager.isUriTemplate(resourceReference.uri())) {
+					// Attempting to autocomplete a fixed resource URI is not an error in
+					// the spec (but probably should be).
+					return EMPTY_COMPLETION_RESULT;
 				}
 
+				McpServerFeatures.AsyncResourceSpecification resourceSpec = this
+					.findResourceSpecification(resourceReference.uri())
+					.orElse(null);
+
+				if (resourceSpec != null) {
+					if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
+						.getVariableNames()
+						.contains(argumentName)) {
+
+						return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+							.message("Argument not found: " + argumentName + " in resource: " + resourceReference.uri())
+							.build());
+					}
+				}
+				else {
+					var templateSpec = this.findResourceTemplateSpecification(resourceReference.uri()).orElse(null);
+					if (templateSpec != null) {
+
+						if (!uriTemplateManagerFactory.create(templateSpec.resourceTemplate().uriTemplate())
+							.getVariableNames()
+							.contains(argumentName)) {
+
+							return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+								.message("Argument not found: " + argumentName + " in resource template: "
+										+ resourceReference.uri())
+								.build());
+						}
+					}
+					else {
+						return Mono.error(RESOURCE_NOT_FOUND.apply(resourceReference.uri()));
+					}
+				}
 			}
 
+			// Handle the completion request using the registered handler
+			// for the given reference.
 			McpServerFeatures.AsyncCompletionSpecification specification = this.completions.get(request.ref());
 
 			if (specification == null) {
-				return Mono.error(new McpError("AsyncCompletionSpecification not found: " + request.ref()));
+				return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+					.message("AsyncCompletionSpecification not found: " + request.ref())
+					.build());
 			}
 
 			return Mono.defer(() -> specification.completionHandler().apply(exchange, request));
@@ -891,9 +1021,9 @@ private McpSchema.CompleteRequest parseCompletionParams(Object object) {
 		String refType = (String) refMap.get("type");
 
 		McpSchema.CompleteReference ref = switch (refType) {
-			case "ref/prompt" -> new McpSchema.PromptReference(refType, (String) refMap.get("name"),
+			case PromptReference.TYPE -> new McpSchema.PromptReference(refType, (String) refMap.get("name"),
 					refMap.get("title") != null ? (String) refMap.get("title") : null);
-			case "ref/resource" -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
+			case ResourceReference.TYPE -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
 			default -> throw new IllegalArgumentException("Invalid ref type: " + refType);
 		};
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
index ec86b5927..8e3ebf9e8 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -298,7 +298,14 @@ abstract class AsyncSpecification> {
 		 */
 		final Map resources = new HashMap<>();
 
-		final List resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map resourceTemplates = new HashMap<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -585,40 +592,39 @@ public AsyncSpecification resources(McpServerFeatures.AsyncResourceSpecificat
 		}
 
 		/**
-		 * Sets the resource templates that define patterns for dynamic resource access.
-		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * 

-		 * Example usage: 
{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }

-		 * @param resourceTemplates List of resource templates. If null, clears existing
-		 * templates.
+		 * Registers multiple resource templates with their specifications using a List.
+		 * This method is useful when resource templates need to be added in bulk from a
+		 * collection.
+		 * @param resourceTemplates Map of template URI to specification. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public AsyncSpecification resourceTemplates(List resourceTemplates) {
+		public AsyncSpecification resourceTemplates(
+				List resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+			for (var resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
+			}
 			return this;
 		}
 
 		/**
-		 * Sets the resource templates using varargs for convenience. This is an
-		 * alternative to {@link #resourceTemplates(List)}.
-		 * @param resourceTemplates The resource templates to set.
+		 * Registers multiple resource templates with their specifications using a List.
+		 * This method is useful when resource templates need to be added in bulk from a
+		 * collection.
+		 * @param resourceTemplates List of template URI to specification. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(List)
 		 */
-		public AsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public AsyncSpecification resourceTemplates(
+				McpServerFeatures.AsyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpServerFeatures.AsyncResourceTemplateSpecification resource : resourceTemplates) {
+				this.resourceTemplates.put(resource.resourceTemplate().uriTemplate(), resource);
 			}
 			return this;
 		}
@@ -887,7 +893,14 @@ abstract class SyncSpecification> {
 		 */
 		final Map resources = new HashMap<>();
 
-		final List resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map resourceTemplates = new HashMap<>();
 
 		JsonSchemaValidator jsonSchemaValidator;
 
@@ -1179,23 +1192,18 @@ public SyncSpecification resources(McpServerFeatures.SyncResourceSpecificatio
 		/**
 		 * Sets the resource templates that define patterns for dynamic resource access.
 		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * 

-		 * Example usage: 
{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }

-		 * @param resourceTemplates List of resource templates. If null, clears existing
-		 * templates.
+		 * @param resourceTemplates List of resource template specifications. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public SyncSpecification resourceTemplates(List resourceTemplates) {
+		public SyncSpecification resourceTemplates(
+				List resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+			for (McpServerFeatures.SyncResourceTemplateSpecification resource : resourceTemplates) {
+				this.resourceTemplates.put(resource.resourceTemplate().uriTemplate(), resource);
+			}
 			return this;
 		}
 
@@ -1207,10 +1215,11 @@ public SyncSpecification resourceTemplates(List resourceTem
 		 * @throws IllegalArgumentException if resourceTemplates is null
 		 * @see #resourceTemplates(List)
 		 */
-		public SyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public SyncSpecification resourceTemplates(
+				McpServerFeatures.SyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpServerFeatures.SyncResourceTemplateSpecification resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
 			}
 			return this;
 		}
@@ -1428,7 +1437,14 @@ class StatelessAsyncSpecification {
 		 */
 		final Map resources = new HashMap<>();
 
-		final List resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map resourceTemplates = new HashMap<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -1684,23 +1700,18 @@ public StatelessAsyncSpecification resources(
 		/**
 		 * Sets the resource templates that define patterns for dynamic resource access.
 		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * 

-		 * Example usage: 
{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }

 		 * @param resourceTemplates List of resource templates. If null, clears existing
 		 * templates.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public StatelessAsyncSpecification resourceTemplates(List resourceTemplates) {
+		public StatelessAsyncSpecification resourceTemplates(
+				List resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+			for (var resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
+			}
 			return this;
 		}
 
@@ -1712,10 +1723,11 @@ public StatelessAsyncSpecification resourceTemplates(List reso
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(List)
 		 */
-		public StatelessAsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public StatelessAsyncSpecification resourceTemplates(
+				McpStatelessServerFeatures.AsyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpStatelessServerFeatures.AsyncResourceTemplateSpecification resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
 			}
 			return this;
 		}
@@ -1888,7 +1900,14 @@ class StatelessSyncSpecification {
 		 */
 		final Map resources = new HashMap<>();
 
-		final List resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map resourceTemplates = new HashMap<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -2144,23 +2163,18 @@ public StatelessSyncSpecification resources(
 		/**
 		 * Sets the resource templates that define patterns for dynamic resource access.
 		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * 

-		 * Example usage: 
{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }

-		 * @param resourceTemplates List of resource templates. If null, clears existing
-		 * templates.
+		 * @param resourceTemplatesSpec List of resource templates. If null, clears
+		 * existing templates.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public StatelessSyncSpecification resourceTemplates(List resourceTemplates) {
-			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+		public StatelessSyncSpecification resourceTemplates(
+				List resourceTemplatesSpec) {
+			Assert.notNull(resourceTemplatesSpec, "Resource templates must not be null");
+			for (var resourceTemplate : resourceTemplatesSpec) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
+			}
 			return this;
 		}
 
@@ -2172,10 +2186,11 @@ public StatelessSyncSpecification resourceTemplates(List resou
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(List)
 		 */
-		public StatelessSyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public StatelessSyncSpecification resourceTemplates(
+				McpStatelessServerFeatures.SyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpStatelessServerFeatures.SyncResourceTemplateSpecification resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
 			}
 			return this;
 		}
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
index cc3fae689..fc5bdfe4e 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
@@ -41,7 +41,7 @@ public class McpServerFeatures {
 	 */
 	record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 			List tools, Map resources,
-			List resourceTemplates,
+			Map resourceTemplates,
 			Map prompts,
 			Map completions,
 			List, Mono>> rootsChangeConsumers,
@@ -53,7 +53,7 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
 		 * @param serverCapabilities The server capabilities
 		 * @param tools The list of tool specifications
 		 * @param resources The map of resource specifications
-		 * @param resourceTemplates The list of resource templates
+		 * @param resourceTemplates The map of resource templates
 		 * @param prompts The map of prompt specifications
 		 * @param rootsChangeConsumers The list of consumers that will be notified when
 		 * the roots list changes
@@ -61,7 +61,7 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
 		 */
 		Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 				List tools, Map resources,
-				List resourceTemplates,
+				Map resourceTemplates,
 				Map prompts,
 				Map completions,
 				List, Mono>> rootsChangeConsumers,
@@ -84,7 +84,7 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
 
 			this.tools = (tools != null) ? tools : List.of();
 			this.resources = (resources != null) ? resources : Map.of();
-			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : List.of();
+			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : Map.of();
 			this.prompts = (prompts != null) ? prompts : Map.of();
 			this.completions = (completions != null) ? completions : Map.of();
 			this.rootsChangeConsumers = (rootsChangeConsumers != null) ? rootsChangeConsumers : List.of();
@@ -112,6 +112,11 @@ static Async fromSync(Sync syncSpec, boolean immediateExecution) {
 				resources.put(key, AsyncResourceSpecification.fromSync(resource, immediateExecution));
 			});
 
+			Map resourceTemplates = new HashMap<>();
+			syncSpec.resourceTemplates().forEach((key, resource) -> {
+				resourceTemplates.put(key, AsyncResourceTemplateSpecification.fromSync(resource, immediateExecution));
+			});
+
 			Map prompts = new HashMap<>();
 			syncSpec.prompts().forEach((key, prompt) -> {
 				prompts.put(key, AsyncPromptSpecification.fromSync(prompt, immediateExecution));
@@ -130,8 +135,8 @@ static Async fromSync(Sync syncSpec, boolean immediateExecution) {
 					.subscribeOn(Schedulers.boundedElastic()));
 			}
 
-			return new Async(syncSpec.serverInfo(), syncSpec.serverCapabilities(), tools, resources,
-					syncSpec.resourceTemplates(), prompts, completions, rootChangeConsumers, syncSpec.instructions());
+			return new Async(syncSpec.serverInfo(), syncSpec.serverCapabilities(), tools, resources, resourceTemplates,
+					prompts, completions, rootChangeConsumers, syncSpec.instructions());
 		}
 	}
 
@@ -151,7 +156,7 @@ static Async fromSync(Sync syncSpec, boolean immediateExecution) {
 	record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 			List tools,
 			Map resources,
-			List resourceTemplates,
+			Map resourceTemplates,
 			Map prompts,
 			Map completions,
 			List>> rootsChangeConsumers, String instructions) {
@@ -171,7 +176,7 @@ record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities se
 		Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 				List tools,
 				Map resources,
-				List resourceTemplates,
+				Map resourceTemplates,
 				Map prompts,
 				Map completions,
 				List>> rootsChangeConsumers,
@@ -194,7 +199,7 @@ record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities se
 
 			this.tools = (tools != null) ? tools : new ArrayList<>();
 			this.resources = (resources != null) ? resources : new HashMap<>();
-			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : new ArrayList<>();
+			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : Map.of();
 			this.prompts = (prompts != null) ? prompts : new HashMap<>();
 			this.completions = (completions != null) ? completions : new HashMap<>();
 			this.rootsChangeConsumers = (rootsChangeConsumers != null) ? rootsChangeConsumers : new ArrayList<>();
@@ -356,6 +361,47 @@ static AsyncResourceSpecification fromSync(SyncResourceSpecification resource, b
 		}
 	}
 
+	/**
+	 * Specification of a resource template with its synchronous handler function.
+	 * Resource templates allow servers to expose parameterized resources using URI
+	 * templates:  URI
+	 * templates.. Arguments may be auto-completed through the
+	 * completion API.
+	 *
+	 * Templates support:
+	 * 
    
+	 * 
  • Parameterized resource definitions
+	 * 
  • Dynamic content generation
+	 * 
  • Consistent resource formatting
+	 * 
  • Contextual data injection
+	 * 

+	 *
+	 * @param resourceTemplate The resource template definition including name,
+	 * description, and parameter schema
+	 * @param readHandler The function that handles resource read requests. The function's
+	 * first argument is an {@link McpSyncServerExchange} upon which the server can
+	 * interact with the connected client. The second arguments is a
+	 * {@link McpSchema.ReadResourceRequest}. {@link McpSchema.ResourceTemplate}
+	 * {@link McpSchema.ReadResourceResult}
+	 */
+	public record AsyncResourceTemplateSpecification(McpSchema.ResourceTemplate resourceTemplate,
+			BiFunction> readHandler) {
+
+		static AsyncResourceTemplateSpecification fromSync(SyncResourceTemplateSpecification resource,
+				boolean immediateExecution) {
+			// FIXME: This is temporary, proper validation should be implemented
+			if (resource == null) {
+				return null;
+			}
+			return new AsyncResourceTemplateSpecification(resource.resourceTemplate(), (exchange, req) -> {
+				var resourceResult = Mono
+					.fromCallable(() -> resource.readHandler().apply(new McpSyncServerExchange(exchange), req));
+				return immediateExecution ? resourceResult : resourceResult.subscribeOn(Schedulers.boundedElastic());
+			});
+		}
+	}
+
 	/**
 	 * Specification of a prompt template with its asynchronous handler function. Prompts
 	 * provide structured templates for AI model interactions, supporting:
@@ -575,6 +621,34 @@ public record SyncResourceSpecification(McpSchema.Resource resource,
 			BiFunction readHandler) {
 	}
 
+	/**
+	 * Specification of a resource template with its synchronous handler function.
+	 * Resource templates allow servers to expose parameterized resources using URI
+	 * templates:  URI
+	 * templates.. Arguments may be auto-completed through the
+	 * completion API.
+	 *
+	 * Templates support:
+	 * 
    
+	 * 
  • Parameterized resource definitions
+	 * 
  • Dynamic content generation
+	 * 
  • Consistent resource formatting
+	 * 
  • Contextual data injection
+	 * 

+	 *
+	 * @param resourceTemplate The resource template definition including name,
+	 * description, and parameter schema
+	 * @param readHandler The function that handles resource read requests. The function's
+	 * first argument is an {@link McpSyncServerExchange} upon which the server can
+	 * interact with the connected client. The second arguments is a
+	 * {@link McpSchema.ReadResourceRequest}. {@link McpSchema.ResourceTemplate}
+	 * {@link McpSchema.ReadResourceResult}
+	 */
+	public record SyncResourceTemplateSpecification(McpSchema.ResourceTemplate resourceTemplate,
+			BiFunction readHandler) {
+	}
+
 	/**
 	 * Specification of a prompt template with its synchronous handler function. Prompts
 	 * provide structured templates for AI model interactions, supporting:
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 1dde58d69..81b50eb2e 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -8,11 +8,15 @@
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
+import io.modelcontextprotocol.server.McpStatelessServerFeatures.AsyncResourceTemplateSpecification;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.CompleteResult.CompleteCompletion;
+import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse;
-import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
+import io.modelcontextprotocol.spec.McpSchema.ResourceReference;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpStatelessServerTransport;
 import io.modelcontextprotocol.util.Assert;
@@ -21,6 +25,7 @@
 import io.modelcontextprotocol.util.Utils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
 import java.time.Duration;
@@ -59,7 +64,7 @@ public class McpStatelessAsyncServer {
 
 	private final CopyOnWriteArrayList tools = new CopyOnWriteArrayList<>();
 
-	private final CopyOnWriteArrayList resourceTemplates = new CopyOnWriteArrayList<>();
+	private final ConcurrentHashMap resourceTemplates = new ConcurrentHashMap<>();
 
 	private final ConcurrentHashMap resources = new ConcurrentHashMap<>();
 
@@ -83,7 +88,7 @@ public class McpStatelessAsyncServer {
 		this.instructions = features.instructions();
 		this.tools.addAll(withStructuredOutputHandling(jsonSchemaValidator, features.tools()));
 		this.resources.putAll(features.resources());
-		this.resourceTemplates.addAll(features.resourceTemplates());
+		this.resourceTemplates.putAll(features.resourceTemplates());
 		this.prompts.putAll(features.prompts());
 		this.completions.putAll(features.completions());
 		this.uriTemplateManagerFactory = uriTemplateManagerFactory;
@@ -405,23 +410,34 @@ private McpStatelessRequestHandler toolsCallRequestHandler() {
 	 */
 	public Mono addResource(McpStatelessServerFeatures.AsyncResourceSpecification resourceSpecification) {
 		if (resourceSpecification == null || resourceSpecification.resource() == null) {
-			return Mono.error(new McpError("Resource must not be null"));
+			return Mono.error(new IllegalArgumentException("Resource must not be null"));
 		}
 
 		if (this.serverCapabilities.resources() == null) {
-			return Mono.error(new McpError("Server must be configured with resource capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with resource capabilities"));
 		}
 
 		return Mono.defer(() -> {
-			if (this.resources.putIfAbsent(resourceSpecification.resource().uri(), resourceSpecification) != null) {
-				return Mono.error(new McpError(
-						"Resource with URI '" + resourceSpecification.resource().uri() + "' already exists"));
+			var previous = this.resources.put(resourceSpecification.resource().uri(), resourceSpecification);
+			if (previous != null) {
+				logger.warn("Replace existing Resource with URI '{}'", resourceSpecification.resource().uri());
+			}
+			else {
+				logger.debug("Added resource handler: {}", resourceSpecification.resource().uri());
 			}
-			logger.debug("Added resource handler: {}", resourceSpecification.resource().uri());
 			return Mono.empty();
 		});
 	}
 
+	/**
+	 * List all registered resources.
+	 * @return A Flux stream of all registered resources
+	 */
+	public Flux listResources() {
+		return Flux.fromIterable(this.resources.values())
+			.map(McpStatelessServerFeatures.AsyncResourceSpecification::resource);
+	}
+
 	/**
 	 * Remove a resource handler at runtime.
 	 * @param resourceUri The URI of the resource handler to remove
@@ -429,19 +445,83 @@ public Mono addResource(McpStatelessServerFeatures.AsyncResourceSpecificat
 	 */
 	public Mono removeResource(String resourceUri) {
 		if (resourceUri == null) {
-			return Mono.error(new McpError("Resource URI must not be null"));
+			return Mono.error(new IllegalArgumentException("Resource URI must not be null"));
 		}
 		if (this.serverCapabilities.resources() == null) {
-			return Mono.error(new McpError("Server must be configured with resource capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with resource capabilities"));
 		}
 
 		return Mono.defer(() -> {
 			McpStatelessServerFeatures.AsyncResourceSpecification removed = this.resources.remove(resourceUri);
 			if (removed != null) {
 				logger.debug("Removed resource handler: {}", resourceUri);
-				return Mono.empty();
 			}
-			return Mono.error(new McpError("Resource with URI '" + resourceUri + "' not found"));
+			else {
+				logger.warn("Resource with URI '{}' not found", resourceUri);
+			}
+			return Mono.empty();
+		});
+	}
+
+	/**
+	 * Add a new resource template at runtime.
+	 * @param resourceTemplateSpecification The resource template to add
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono addResourceTemplate(
+			McpStatelessServerFeatures.AsyncResourceTemplateSpecification resourceTemplateSpecification) {
+
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new IllegalStateException(
+					"Server must be configured with resource capabilities to allow adding resource templates"));
+		}
+
+		return Mono.defer(() -> {
+			var previous = this.resourceTemplates.put(resourceTemplateSpecification.resourceTemplate().uriTemplate(),
+					resourceTemplateSpecification);
+			if (previous != null) {
+				logger.warn("Replace existing Resource Template with URI '{}'",
+						resourceTemplateSpecification.resourceTemplate().uriTemplate());
+			}
+			else {
+				logger.debug("Added resource template handler: {}",
+						resourceTemplateSpecification.resourceTemplate().uriTemplate());
+			}
+			return Mono.empty();
+		});
+	}
+
+	/**
+	 * List all registered resource templates.
+	 * @return A Flux stream of all registered resource templates
+	 */
+	public Flux listResourceTemplates() {
+		return Flux.fromIterable(this.resourceTemplates.values())
+			.map(McpStatelessServerFeatures.AsyncResourceTemplateSpecification::resourceTemplate);
+	}
+
+	/**
+	 * Remove a resource template at runtime.
+	 * @param uriTemplate The URI template of the resource template to remove
+	 * @return Mono that completes when clients have been notified of the change
+	 */
+	public Mono removeResourceTemplate(String uriTemplate) {
+
+		if (this.serverCapabilities.resources() == null) {
+			return Mono.error(new IllegalStateException(
+					"Server must be configured with resource capabilities to allow removing resource templates"));
+		}
+
+		return Mono.defer(() -> {
+			McpStatelessServerFeatures.AsyncResourceTemplateSpecification removed = this.resourceTemplates
+				.remove(uriTemplate);
+			if (removed != null) {
+				logger.debug("Removed resource template: {}", uriTemplate);
+			}
+			else {
+				logger.warn("Ignore as a Resource Template with URI '{}' not found", uriTemplate);
+			}
+			return Mono.empty();
 		});
 	}
 
@@ -456,26 +536,13 @@ private McpStatelessRequestHandler resourcesListR
 	}
 
 	private McpStatelessRequestHandler resourceTemplateListRequestHandler() {
-		return (ctx, params) -> Mono.just(new McpSchema.ListResourceTemplatesResult(this.getResourceTemplates(), null));
-
-	}
-
-	private List getResourceTemplates() {
-		var list = new ArrayList<>(this.resourceTemplates);
-		List resourceTemplates = this.resources.keySet()
-			.stream()
-			.filter(uri -> uri.contains("{"))
-			.map(uri -> {
-				var resource = this.resources.get(uri).resource();
-				var template = new ResourceTemplate(resource.uri(), resource.name(), resource.title(),
-						resource.description(), resource.mimeType(), resource.annotations());
-				return template;
-			})
-			.toList();
-
-		list.addAll(resourceTemplates);
-
-		return list;
+		return (exchange, params) -> {
+			var resourceList = this.resourceTemplates.values()
+				.stream()
+				.map(AsyncResourceTemplateSpecification::resourceTemplate)
+				.toList();
+			return Mono.just(new McpSchema.ListResourceTemplatesResult(resourceList, null));
+		};
 	}
 
 	private McpStatelessRequestHandler resourcesReadRequestHandler() {
@@ -483,15 +550,35 @@ private McpStatelessRequestHandler resourcesReadRe
 			McpSchema.ReadResourceRequest resourceRequest = jsonMapper.convertValue(params, new TypeRef<>() {
 			});
 			var resourceUri = resourceRequest.uri();
-			return asyncResourceSpecification(resourceUri).map(spec -> spec.readHandler().apply(ctx, resourceRequest))
-				.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
+
+			// First try to find a static resource specification
+			// Static resources have exact URIs
+			return this.findResourceSpecification(resourceUri)
+				.map(spec -> spec.readHandler().apply(ctx, resourceRequest))
+				.orElseGet(() -> {
+					// If not found, try to find a dynamic resource specification
+					// Dynamic resources have URI templates
+					return this.findResourceTemplateSpecification(resourceUri)
+						.map(spec -> spec.readHandler().apply(ctx, resourceRequest))
+						.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
+				});
+
 		};
 	}
 
-	private Optional asyncResourceSpecification(String uri) {
-		return resources.values()
+	private Optional findResourceSpecification(String uri) {
+		var result = this.resources.values()
 			.stream()
-			.filter(spec -> uriTemplateManagerFactory.create(spec.resource().uri()).matches(uri))
+			.filter(spec -> this.uriTemplateManagerFactory.create(spec.resource().uri()).matches(uri))
+			.findFirst();
+		return result;
+	}
+
+	private Optional findResourceTemplateSpecification(
+			String uri) {
+		return this.resourceTemplates.values()
+			.stream()
+			.filter(spec -> this.uriTemplateManagerFactory.create(spec.resourceTemplate().uriTemplate()).matches(uri))
 			.findFirst();
 	}
 
@@ -582,53 +669,105 @@ private McpStatelessRequestHandler promptsGetRequestH
 		};
 	}
 
+	private static final Mono EMPTY_COMPLETION_RESULT = Mono
+		.just(new McpSchema.CompleteResult(new CompleteCompletion(List.of(), 0, false)));
+
 	private McpStatelessRequestHandler completionCompleteRequestHandler() {
 		return (ctx, params) -> {
 			McpSchema.CompleteRequest request = parseCompletionParams(params);
 
 			if (request.ref() == null) {
-				return Mono.error(new McpError("ref must not be null"));
+				return Mono.error(
+						McpError.builder(ErrorCodes.INVALID_PARAMS).message("Completion ref must not be null").build());
 			}
 
 			if (request.ref().type() == null) {
-				return Mono.error(new McpError("type must not be null"));
+				return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+					.message("Completion ref type must not be null")
+					.build());
 			}
 
 			String type = request.ref().type();
 
 			String argumentName = request.argument().name();
 
-			// check if the referenced resource exists
-			if (type.equals("ref/prompt") && request.ref() instanceof McpSchema.PromptReference promptReference) {
+			// Check if valid a Prompt exists for this completion request
+			if (type.equals(PromptReference.TYPE)
+					&& request.ref() instanceof McpSchema.PromptReference promptReference) {
+
 				McpStatelessServerFeatures.AsyncPromptSpecification promptSpec = this.prompts
 					.get(promptReference.name());
 				if (promptSpec == null) {
-					return Mono.error(new McpError("Prompt not found: " + promptReference.name()));
+					return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+						.message("Prompt not found: " + promptReference.name())
+						.build());
 				}
-				if (promptSpec.prompt().arguments().stream().noneMatch(arg -> arg.name().equals(argumentName))) {
+				if (!promptSpec.prompt()
+					.arguments()
+					.stream()
+					.filter(arg -> arg.name().equals(argumentName))
+					.findFirst()
+					.isPresent()) {
 
-					return Mono.error(new McpError("Argument not found: " + argumentName));
+					logger.warn("Argument not found: {} in prompt: {}", argumentName, promptReference.name());
+
+					return EMPTY_COMPLETION_RESULT;
 				}
 			}
 
-			if (type.equals("ref/resource") && request.ref() instanceof McpSchema.ResourceReference resourceReference) {
-				McpStatelessServerFeatures.AsyncResourceSpecification resourceSpec = resources
-					.get(resourceReference.uri());
-				if (resourceSpec == null) {
-					return Mono.error(RESOURCE_NOT_FOUND.apply(resourceReference.uri()));
-				}
-				if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
-					.getVariableNames()
-					.contains(argumentName)) {
-					return Mono.error(new McpError("Argument not found: " + argumentName));
+			// Check if valid Resource or ResourceTemplate exists for this completion
+			// request
+			if (type.equals(ResourceReference.TYPE)
+					&& request.ref() instanceof McpSchema.ResourceReference resourceReference) {
+
+				var uriTemplateManager = uriTemplateManagerFactory.create(resourceReference.uri());
+
+				if (!uriTemplateManager.isUriTemplate(resourceReference.uri())) {
+					// Attempting to autocomplete a fixed resource URI is not an error in
+					// the spec (but probably should be).
+					return EMPTY_COMPLETION_RESULT;
 				}
 
+				McpStatelessServerFeatures.AsyncResourceSpecification resourceSpec = this
+					.findResourceSpecification(resourceReference.uri())
+					.orElse(null);
+
+				if (resourceSpec != null) {
+					if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
+						.getVariableNames()
+						.contains(argumentName)) {
+
+						return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+							.message("Argument not found: " + argumentName + " in resource: " + resourceReference.uri())
+							.build());
+					}
+				}
+				else {
+					var templateSpec = this.findResourceTemplateSpecification(resourceReference.uri()).orElse(null);
+					if (templateSpec != null) {
+
+						if (!uriTemplateManagerFactory.create(templateSpec.resourceTemplate().uriTemplate())
+							.getVariableNames()
+							.contains(argumentName)) {
+
+							return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+								.message("Argument not found: " + argumentName + " in resource template: "
+										+ resourceReference.uri())
+								.build());
+						}
+					}
+					else {
+						return Mono.error(RESOURCE_NOT_FOUND.apply(resourceReference.uri()));
+					}
+				}
 			}
 
 			McpStatelessServerFeatures.AsyncCompletionSpecification specification = this.completions.get(request.ref());
 
 			if (specification == null) {
-				return Mono.error(new McpError("AsyncCompletionSpecification not found: " + request.ref()));
+				return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+					.message("AsyncCompletionSpecification not found: " + request.ref())
+					.build());
 			}
 
 			return specification.completionHandler().apply(ctx, request);
@@ -657,9 +796,9 @@ private McpSchema.CompleteRequest parseCompletionParams(Object object) {
 		String refType = (String) refMap.get("type");
 
 		McpSchema.CompleteReference ref = switch (refType) {
-			case "ref/prompt" -> new McpSchema.PromptReference(refType, (String) refMap.get("name"),
+			case PromptReference.TYPE -> new McpSchema.PromptReference(refType, (String) refMap.get("name"),
 					refMap.get("title") != null ? (String) refMap.get("title") : null);
-			case "ref/resource" -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
+			case ResourceReference.TYPE -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
 			default -> throw new IllegalArgumentException("Invalid ref type: " + refType);
 		};
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
index df44d50c4..a15681ba5 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java
@@ -4,6 +4,12 @@
 
 package io.modelcontextprotocol.server;
 
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.BiFunction;
+
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
@@ -12,12 +18,6 @@
 import reactor.core.publisher.Mono;
 import reactor.core.scheduler.Schedulers;
 
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.function.BiFunction;
-
 /**
  * MCP stateless server features specification that a particular server can choose to
  * support.
@@ -34,13 +34,14 @@ public class McpStatelessServerFeatures {
 	 * @param serverCapabilities The server capabilities
 	 * @param tools The list of tool specifications
 	 * @param resources The map of resource specifications
-	 * @param resourceTemplates The list of resource templates
+	 * @param resourceTemplates The map of resource templates
 	 * @param prompts The map of prompt specifications
 	 * @param instructions The server instructions text
 	 */
 	record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 			List tools,
-			Map resources, List resourceTemplates,
+			Map resources,
+			Map resourceTemplates,
 			Map prompts,
 			Map completions,
 			String instructions) {
@@ -51,13 +52,14 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
 		 * @param serverCapabilities The server capabilities
 		 * @param tools The list of tool specifications
 		 * @param resources The map of resource specifications
-		 * @param resourceTemplates The list of resource templates
+		 * @param resourceTemplates The map of resource templates
 		 * @param prompts The map of prompt specifications
 		 * @param instructions The server instructions text
 		 */
 		Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 				List tools,
-				Map resources, List resourceTemplates,
+				Map resources,
+				Map resourceTemplates,
 				Map prompts,
 				Map completions,
 				String instructions) {
@@ -76,7 +78,7 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
 
 			this.tools = (tools != null) ? tools : List.of();
 			this.resources = (resources != null) ? resources : Map.of();
-			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : List.of();
+			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : Map.of();
 			this.prompts = (prompts != null) ? prompts : Map.of();
 			this.completions = (completions != null) ? completions : Map.of();
 			this.instructions = instructions;
@@ -103,6 +105,11 @@ static Async fromSync(Sync syncSpec, boolean immediateExecution) {
 				resources.put(key, AsyncResourceSpecification.fromSync(resource, immediateExecution));
 			});
 
+			Map resourceTemplates = new HashMap<>();
+			syncSpec.resourceTemplates().forEach((key, resource) -> {
+				resourceTemplates.put(key, AsyncResourceTemplateSpecification.fromSync(resource, immediateExecution));
+			});
+
 			Map prompts = new HashMap<>();
 			syncSpec.prompts().forEach((key, prompt) -> {
 				prompts.put(key, AsyncPromptSpecification.fromSync(prompt, immediateExecution));
@@ -113,8 +120,8 @@ static Async fromSync(Sync syncSpec, boolean immediateExecution) {
 				completions.put(key, AsyncCompletionSpecification.fromSync(completion, immediateExecution));
 			});
 
-			return new Async(syncSpec.serverInfo(), syncSpec.serverCapabilities(), tools, resources,
-					syncSpec.resourceTemplates(), prompts, completions, syncSpec.instructions());
+			return new Async(syncSpec.serverInfo(), syncSpec.serverCapabilities(), tools, resources, resourceTemplates,
+					prompts, completions, syncSpec.instructions());
 		}
 	}
 
@@ -125,14 +132,14 @@ static Async fromSync(Sync syncSpec, boolean immediateExecution) {
 	 * @param serverCapabilities The server capabilities
 	 * @param tools The list of tool specifications
 	 * @param resources The map of resource specifications
-	 * @param resourceTemplates The list of resource templates
+	 * @param resourceTemplates The map of resource templates
 	 * @param prompts The map of prompt specifications
 	 * @param instructions The server instructions text
 	 */
 	record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 			List tools,
 			Map resources,
-			List resourceTemplates,
+			Map resourceTemplates,
 			Map prompts,
 			Map completions,
 			String instructions) {
@@ -143,14 +150,14 @@ record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities se
 		 * @param serverCapabilities The server capabilities
 		 * @param tools The list of tool specifications
 		 * @param resources The map of resource specifications
-		 * @param resourceTemplates The list of resource templates
+		 * @param resourceTemplates The map of resource templates
 		 * @param prompts The map of prompt specifications
 		 * @param instructions The server instructions text
 		 */
 		Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
 				List tools,
 				Map resources,
-				List resourceTemplates,
+				Map resourceTemplates,
 				Map prompts,
 				Map completions,
 				String instructions) {
@@ -172,7 +179,7 @@ record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities se
 
 			this.tools = (tools != null) ? tools : new ArrayList<>();
 			this.resources = (resources != null) ? resources : new HashMap<>();
-			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : new ArrayList<>();
+			this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : Map.of();
 			this.prompts = (prompts != null) ? prompts : new HashMap<>();
 			this.completions = (completions != null) ? completions : new HashMap<>();
 			this.instructions = instructions;
@@ -296,6 +303,46 @@ static AsyncResourceSpecification fromSync(SyncResourceSpecification resource, b
 		}
 	}
 
+	/**
+	 * Specification of a resource template with its synchronous handler function.
+	 * Resource templates allow servers to expose parameterized resources using URI
+	 * templates:  URI
+	 * templates.. Arguments may be auto-completed through the
+	 * completion API.
+	 *
+	 * Templates support:
+	 * 
    
+	 * 
  • Parameterized resource definitions
+	 * 
  • Dynamic content generation
+	 * 
  • Consistent resource formatting
+	 * 
  • Contextual data injection
+	 * 

+	 *
+	 * @param resourceTemplate The resource template definition including name,
+	 * description, and parameter schema
+	 * @param readHandler The function that handles resource read requests. The function's
+	 * first argument is an {@link McpTransportContext} upon which the server can interact
+	 * with the connected client. The second arguments is a
+	 * {@link McpSchema.ReadResourceRequest}. {@link McpSchema.ResourceTemplate}
+	 * {@link McpSchema.ReadResourceResult}
+	 */
+	public record AsyncResourceTemplateSpecification(McpSchema.ResourceTemplate resourceTemplate,
+			BiFunction> readHandler) {
+
+		static AsyncResourceTemplateSpecification fromSync(SyncResourceTemplateSpecification resource,
+				boolean immediateExecution) {
+			// FIXME: This is temporary, proper validation should be implemented
+			if (resource == null) {
+				return null;
+			}
+			return new AsyncResourceTemplateSpecification(resource.resourceTemplate(), (ctx, req) -> {
+				var resourceResult = Mono.fromCallable(() -> resource.readHandler().apply(ctx, req));
+				return immediateExecution ? resourceResult : resourceResult.subscribeOn(Schedulers.boundedElastic());
+			});
+		}
+	}
+
 	/**
 	 * Specification of a prompt template with its asynchronous handler function. Prompts
 	 * provide structured templates for AI model interactions, supporting:
@@ -446,6 +493,34 @@ public record SyncResourceSpecification(McpSchema.Resource resource,
 			BiFunction readHandler) {
 	}
 
+	/**
+	 * Specification of a resource template with its synchronous handler function.
+	 * Resource templates allow servers to expose parameterized resources using URI
+	 * templates:  URI
+	 * templates.. Arguments may be auto-completed through the
+	 * completion API.
+	 *
+	 * Templates support:
+	 * 
    
+	 * 
  • Parameterized resource definitions
+	 * 
  • Dynamic content generation
+	 * 
  • Consistent resource formatting
+	 * 
  • Contextual data injection
+	 * 

+	 *
+	 * @param resourceTemplate The resource template definition including name,
+	 * description, and parameter schema
+	 * @param readHandler The function that handles resource read requests. The function's
+	 * first argument is an {@link McpTransportContext} upon which the server can interact
+	 * with the connected client. The second arguments is a
+	 * {@link McpSchema.ReadResourceRequest}. {@link McpSchema.ResourceTemplate}
+	 * {@link McpSchema.ReadResourceResult}
+	 */
+	public record SyncResourceTemplateSpecification(McpSchema.ResourceTemplate resourceTemplate,
+			BiFunction readHandler) {
+	}
+
 	/**
 	 * Specification of a prompt template with its synchronous handler function. Prompts
 	 * provide structured templates for AI model interactions, supporting:
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
index 0151a754b..65833d135 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
@@ -93,6 +93,14 @@ public void addResource(McpStatelessServerFeatures.SyncResourceSpecification res
 			.block();
 	}
 
+	/**
+	 * List all registered resources.
+	 * @return A list of all registered resources
+	 */
+	public List listResources() {
+		return this.asyncServer.listResources().collectList().block();
+	}
+
 	/**
 	 * Remove a resource handler at runtime.
 	 * @param resourceUri The URI of the resource handler to remove
@@ -101,6 +109,34 @@ public void removeResource(String resourceUri) {
 		this.asyncServer.removeResource(resourceUri).block();
 	}
 
+	/**
+	 * Add a new resource template.
+	 * @param resourceTemplateSpecification The resource template specification to add
+	 */
+	public void addResourceTemplate(
+			McpStatelessServerFeatures.SyncResourceTemplateSpecification resourceTemplateSpecification) {
+		this.asyncServer
+			.addResourceTemplate(McpStatelessServerFeatures.AsyncResourceTemplateSpecification
+				.fromSync(resourceTemplateSpecification, this.immediateExecution))
+			.block();
+	}
+
+	/**
+	 * List all registered resource templates.
+	 * @return A list of all registered resource templates
+	 */
+	public List listResourceTemplates() {
+		return this.asyncServer.listResourceTemplates().collectList().block();
+	}
+
+	/**
+	 * Remove a resource template.
+	 * @param uriTemplate The URI template of the resource template to remove
+	 */
+	public void removeResourceTemplate(String uriTemplate) {
+		this.asyncServer.removeResourceTemplate(uriTemplate).block();
+	}
+
 	/**
 	 * Add a new prompt handler at runtime.
 	 * @param promptSpecification The prompt handler to add
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
index 5adda1a74..2852937ab 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
@@ -4,6 +4,8 @@
 
 package io.modelcontextprotocol.server;
 
+import java.util.List;
+
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 import io.modelcontextprotocol.util.Assert;
@@ -97,15 +99,23 @@ public void removeTool(String toolName) {
 
 	/**
 	 * Add a new resource handler.
-	 * @param resourceHandler The resource handler to add
+	 * @param resourceSpecification The resource specification to add
 	 */
-	public void addResource(McpServerFeatures.SyncResourceSpecification resourceHandler) {
+	public void addResource(McpServerFeatures.SyncResourceSpecification resourceSpecification) {
 		this.asyncServer
-			.addResource(
-					McpServerFeatures.AsyncResourceSpecification.fromSync(resourceHandler, this.immediateExecution))
+			.addResource(McpServerFeatures.AsyncResourceSpecification.fromSync(resourceSpecification,
+					this.immediateExecution))
 			.block();
 	}
 
+	/**
+	 * List all registered resources.
+	 * @return A list of all registered resources
+	 */
+	public List listResources() {
+		return this.asyncServer.listResources().collectList().block();
+	}
+
 	/**
 	 * Remove a resource handler.
 	 * @param resourceUri The URI of the resource handler to remove
@@ -114,6 +124,33 @@ public void removeResource(String resourceUri) {
 		this.asyncServer.removeResource(resourceUri).block();
 	}
 
+	/**
+	 * Add a new resource template.
+	 * @param resourceTemplateSpecification The resource template specification to add
+	 */
+	public void addResourceTemplate(McpServerFeatures.SyncResourceTemplateSpecification resourceTemplateSpecification) {
+		this.asyncServer
+			.addResourceTemplate(McpServerFeatures.AsyncResourceTemplateSpecification
+				.fromSync(resourceTemplateSpecification, this.immediateExecution))
+			.block();
+	}
+
+	/**
+	 * List all registered resource templates.
+	 * @return A list of all registered resource templates
+	 */
+	public List listResourceTemplates() {
+		return this.asyncServer.listResourceTemplates().collectList().block();
+	}
+
+	/**
+	 * Remove a resource template.
+	 * @param uriTemplate The URI template of the resource template to remove
+	 */
+	public void removeResourceTemplate(String uriTemplate) {
+		this.asyncServer.removeResourceTemplate(uriTemplate).block();
+	}
+
 	/**
 	 * Add a new prompt handler.
 	 * @param promptSpecification The prompt specification to add
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
index 4f717306a..5e6f5990b 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
@@ -36,6 +36,15 @@ public JSONRPCError getJsonRpcError() {
 		return jsonRpcError;
 	}
 
+	@Override
+	public String toString() {
+		var message = super.toString();
+		if (jsonRpcError != null) {
+			return message + jsonRpcError.toString();
+		}
+		return message;
+	}
+
 	public static Builder builder(int errorCode) {
 		return new Builder(errorCode);
 	}
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 44da6dd39..792aa54fa 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -20,7 +20,6 @@
 import com.fasterxml.jackson.annotation.JsonTypeInfo.As;
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
-
 import io.modelcontextprotocol.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -150,12 +149,25 @@ public static final class ErrorCodes {
 
 	}
 
-	public sealed interface Request
-			permits InitializeRequest, CallToolRequest, CreateMessageRequest, ElicitRequest, CompleteRequest,
-			GetPromptRequest, ReadResourceRequest, SubscribeRequest, UnsubscribeRequest, PaginatedRequest {
+	/**
+	 * Base interface for MCP objects that include optional metadata in the `_meta` field.
+	 */
+	public interface Meta {
 
+		/**
+		 * @see Specification
+		 * for notes on _meta usage
+		 * @return additional metadata related to this resource.
+		 */
 		Map meta();
 
+	}
+
+	public sealed interface Request extends Meta
+			permits InitializeRequest, CallToolRequest, CreateMessageRequest, ElicitRequest, CompleteRequest,
+			GetPromptRequest, ReadResourceRequest, SubscribeRequest, UnsubscribeRequest, PaginatedRequest {
+
 		default String progressToken() {
 			if (meta() != null && meta().containsKey("progressToken")) {
 				return meta().get("progressToken").toString();
@@ -165,19 +177,15 @@ default String progressToken() {
 
 	}
 
-	public sealed interface Result permits InitializeResult, ListResourcesResult, ListResourceTemplatesResult,
-			ReadResourceResult, ListPromptsResult, GetPromptResult, ListToolsResult, CallToolResult,
-			CreateMessageResult, ElicitResult, CompleteResult, ListRootsResult {
-
-		Map meta();
+	public sealed interface Result extends Meta permits InitializeResult, ListResourcesResult,
+			ListResourceTemplatesResult, ReadResourceResult, ListPromptsResult, GetPromptResult, ListToolsResult,
+			CallToolResult, CreateMessageResult, ElicitResult, CompleteResult, ListRootsResult {
 
 	}
 
-	public sealed interface Notification
+	public sealed interface Notification extends Meta
 			permits ProgressNotification, LoggingMessageNotification, ResourcesUpdatedNotification {
 
-		Map meta();
-
 	}
 
 	private static final TypeRef> MAP_TYPE_REF = new TypeRef<>() {
@@ -609,7 +617,7 @@ public ServerCapabilities build() {
 	public record Implementation( // @formatter:off
 		@JsonProperty("name") String name,
 		@JsonProperty("title") String title,
-		@JsonProperty("version") String version) implements BaseMetadata { // @formatter:on			
+		@JsonProperty("version") String version) implements Identifier { // @formatter:on			
 
 		public Implementation(String name, String version) {
 			this(name, null, version);
@@ -668,7 +676,9 @@ public Annotations(List audience, Double priority) {
 	 * interface is implemented by both {@link Resource} and {@link ResourceLink} to
 	 * provide a consistent way to access resource metadata.
 	 */
-	public interface ResourceContent extends BaseMetadata {
+	public interface ResourceContent extends Identifier, Annotated, Meta {
+
+		// name & title from Identifier
 
 		String uri();
 
@@ -678,15 +688,15 @@ public interface ResourceContent extends BaseMetadata {
 
 		Long size();
 
-		Annotations annotations();
+		// annotations from Annotated
+		// meta from Meta
 
 	}
 
 	/**
-	 * Base interface for metadata with name (identifier) and title (display name)
-	 * properties.
+	 * Base interface with name (identifier) and title (display name) properties.
 	 */
-	public interface BaseMetadata {
+	public interface Identifier {
 
 		/**
 		 * Intended for programmatic or logical use, but used as a display name in past
@@ -732,7 +742,7 @@ public record Resource( // @formatter:off
 		@JsonProperty("mimeType") String mimeType,
 		@JsonProperty("size") Long size,
 		@JsonProperty("annotations") Annotations annotations,
-		@JsonProperty("_meta") Map meta) implements Annotated, ResourceContent { // @formatter:on
+		@JsonProperty("_meta") Map meta) implements ResourceContent { // @formatter:on
 
 		/**
 		 * @deprecated Only exists for backwards-compatibility purposes. Use
@@ -862,7 +872,7 @@ public record ResourceTemplate( // @formatter:off
 		@JsonProperty("description") String description,
 		@JsonProperty("mimeType") String mimeType,
 		@JsonProperty("annotations") Annotations annotations,
-		@JsonProperty("_meta") Map meta) implements Annotated, BaseMetadata { // @formatter:on
+		@JsonProperty("_meta") Map meta) implements Annotated, Identifier, Meta { // @formatter:on
 
 		public ResourceTemplate(String uriTemplate, String name, String title, String description, String mimeType,
 				Annotations annotations) {
@@ -873,6 +883,70 @@ public ResourceTemplate(String uriTemplate, String name, String description, Str
 				Annotations annotations) {
 			this(uriTemplate, name, null, description, mimeType, annotations);
 		}
+
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		public static class Builder {
+
+			private String uriTemplate;
+
+			private String name;
+
+			private String title;
+
+			private String description;
+
+			private String mimeType;
+
+			private Annotations annotations;
+
+			private Map meta;
+
+			public Builder uriTemplate(String uri) {
+				this.uriTemplate = uri;
+				return this;
+			}
+
+			public Builder name(String name) {
+				this.name = name;
+				return this;
+			}
+
+			public Builder title(String title) {
+				this.title = title;
+				return this;
+			}
+
+			public Builder description(String description) {
+				this.description = description;
+				return this;
+			}
+
+			public Builder mimeType(String mimeType) {
+				this.mimeType = mimeType;
+				return this;
+			}
+
+			public Builder annotations(Annotations annotations) {
+				this.annotations = annotations;
+				return this;
+			}
+
+			public Builder meta(Map meta) {
+				this.meta = meta;
+				return this;
+			}
+
+			public ResourceTemplate build() {
+				Assert.hasText(uriTemplate, "uri must not be empty");
+				Assert.hasText(name, "name must not be empty");
+
+				return new ResourceTemplate(uriTemplate, name, title, description, mimeType, annotations, meta);
+			}
+
+		}
 	}
 
 	/**
@@ -993,7 +1067,7 @@ public UnsubscribeRequest(String uri) {
 	@JsonTypeInfo(use = JsonTypeInfo.Id.DEDUCTION, include = As.PROPERTY)
 	@JsonSubTypes({ @JsonSubTypes.Type(value = TextResourceContents.class, name = "text"),
 			@JsonSubTypes.Type(value = BlobResourceContents.class, name = "blob") })
-	public sealed interface ResourceContents permits TextResourceContents, BlobResourceContents {
+	public sealed interface ResourceContents extends Meta permits TextResourceContents, BlobResourceContents {
 
 		/**
 		 * The URI of this resource.
@@ -1007,14 +1081,6 @@ public sealed interface ResourceContents permits TextResourceContents, BlobResou
 		 */
 		String mimeType();
 
-		/**
-		 * @see Specification
-		 * for notes on _meta usage
-		 * @return additional metadata related to this resource.
-		 */
-		Map meta();
-
 	}
 
 	/**
@@ -1081,7 +1147,7 @@ public record Prompt( // @formatter:off
 		@JsonProperty("title") String title,
 		@JsonProperty("description") String description,
 		@JsonProperty("arguments") List arguments,
-		@JsonProperty("_meta") Map meta) implements BaseMetadata { // @formatter:on
+		@JsonProperty("_meta") Map meta) implements Identifier { // @formatter:on
 
 		public Prompt(String name, String description, List arguments) {
 			this(name, null, description, arguments != null ? arguments : new ArrayList<>());
@@ -1106,7 +1172,7 @@ public record PromptArgument( // @formatter:off
 		@JsonProperty("name") String name,
 		@JsonProperty("title") String title,
 		@JsonProperty("description") String description,
-		@JsonProperty("required") Boolean required) implements BaseMetadata { // @formatter:on
+		@JsonProperty("required") Boolean required) implements Identifier { // @formatter:on
 
 		public PromptArgument(String name, String description, Boolean required) {
 			this(name, null, description, required);
@@ -2306,14 +2372,16 @@ public sealed interface CompleteReference permits PromptReference, ResourceRefer
 	public record PromptReference( // @formatter:off
 		@JsonProperty("type") String type,
 		@JsonProperty("name") String name,
-		@JsonProperty("title") String title ) implements McpSchema.CompleteReference, BaseMetadata { // @formatter:on
+		@JsonProperty("title") String title ) implements McpSchema.CompleteReference, Identifier { // @formatter:on
+
+		public static final String TYPE = "ref/prompt";
 
 		public PromptReference(String type, String name) {
 			this(type, name, null);
 		}
 
 		public PromptReference(String name) {
-			this("ref/prompt", name, null);
+			this(TYPE, name, null);
 		}
 
 		@Override
@@ -2350,8 +2418,10 @@ public record ResourceReference( // @formatter:off
 		@JsonProperty("type") String type,
 		@JsonProperty("uri") String uri) implements McpSchema.CompleteReference { // @formatter:on
 
+		public static final String TYPE = "ref/resource";
+
 		public ResourceReference(String uri) {
-			this("ref/resource", uri);
+			this(TYPE, uri);
 		}
 
 		@Override
@@ -2414,8 +2484,9 @@ public record CompleteContext(@JsonProperty("arguments") Map arg
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
-	public record CompleteResult(@JsonProperty("completion") CompleteCompletion completion,
-			@JsonProperty("_meta") Map meta) implements Result {
+	public record CompleteResult(// @formatter:off
+			@JsonProperty("completion") CompleteCompletion completion,
+			@JsonProperty("_meta") Map meta) implements Result { // @formatter:on
 
 		// backwards compatibility constructor
 		public CompleteResult(CompleteCompletion completion) {
@@ -2447,9 +2518,8 @@ public record CompleteCompletion( // @formatter:off
 			@JsonSubTypes.Type(value = AudioContent.class, name = "audio"),
 			@JsonSubTypes.Type(value = EmbeddedResource.class, name = "resource"),
 			@JsonSubTypes.Type(value = ResourceLink.class, name = "resource_link") })
-	public sealed interface Content permits TextContent, ImageContent, AudioContent, EmbeddedResource, ResourceLink {
-
-		Map meta();
+	public sealed interface Content extends Meta
+			permits TextContent, ImageContent, AudioContent, EmbeddedResource, ResourceLink {
 
 		default String type() {
 			if (this instanceof TextContent) {
@@ -2674,29 +2744,7 @@ public record ResourceLink( // @formatter:off
 		@JsonProperty("mimeType") String mimeType,
 		@JsonProperty("size") Long size,
 		@JsonProperty("annotations") Annotations annotations,
-		@JsonProperty("_meta") Map meta) implements Annotated, Content, ResourceContent { // @formatter:on
-
-		/**
-		 * @deprecated Only exists for backwards-compatibility purposes. Use
-		 * {@link ResourceLink#ResourceLink(String, String, String, String, String, Long, Annotations)}
-		 * instead.
-		 */
-		@Deprecated
-		public ResourceLink(String name, String title, String uri, String description, String mimeType, Long size,
-				Annotations annotations) {
-			this(name, title, uri, description, mimeType, size, annotations, null);
-		}
-
-		/**
-		 * @deprecated Only exists for backwards-compatibility purposes. Use
-		 * {@link ResourceLink#ResourceLink(String, String, String, String, String, Long, Annotations)}
-		 * instead.
-		 */
-		@Deprecated
-		public ResourceLink(String name, String uri, String description, String mimeType, Long size,
-				Annotations annotations) {
-			this(name, null, uri, description, mimeType, size, annotations);
-		}
+		@JsonProperty("_meta") Map meta) implements Content, ResourceContent { // @formatter:on
 
 		public static Builder builder() {
 			return new Builder();
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
index b2e9a5285..ef51183a1 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
@@ -33,9 +33,7 @@ public class DefaultMcpUriTemplateManager implements McpUriTemplateManager {
 	 * @param uriTemplate The URI template to be used for variable extraction
 	 */
 	public DefaultMcpUriTemplateManager(String uriTemplate) {
-		if (uriTemplate == null || uriTemplate.isEmpty()) {
-			throw new IllegalArgumentException("URI template must not be null or empty");
-		}
+		Assert.hasText(uriTemplate, "URI template must not be null or empty");
 		this.uriTemplate = uriTemplate;
 	}
 
@@ -48,10 +46,6 @@ public DefaultMcpUriTemplateManager(String uriTemplate) {
 	 */
 	@Override
 	public List getVariableNames() {
-		if (uriTemplate == null || uriTemplate.isEmpty()) {
-			return List.of();
-		}
-
 		List variables = new ArrayList<>();
 		Matcher matcher = URI_VARIABLE_PATTERN.matcher(this.uriTemplate);
 
@@ -81,7 +75,7 @@ public Map extractVariableValues(String requestUri) {
 		Map variableValues = new HashMap<>();
 		List uriVariables = this.getVariableNames();
 
-		if (requestUri == null || uriVariables.isEmpty()) {
+		if (!Utils.hasText(requestUri) || uriVariables.isEmpty()) {
 			return variableValues;
 		}
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index 93e49bc1c..f8f17cdfb 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -4,18 +4,9 @@
 
 package io.modelcontextprotocol.server;
 
-import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
 import java.time.Duration;
 import java.util.List;
 
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
@@ -27,9 +18,17 @@
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
 /**
  * Test suite for the {@link McpAsyncServer} that can be used with different
  * {@link io.modelcontextprotocol.spec.McpServerTransportProvider} implementations.
@@ -344,7 +343,7 @@ void testAddResourceWithNullSpecification() {
 
 		StepVerifier.create(mcpAsyncServer.addResource((McpServerFeatures.AsyncResourceSpecification) null))
 			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class).hasMessage("Resource must not be null");
+				assertThat(error).isInstanceOf(IllegalArgumentException.class).hasMessage("Resource must not be null");
 			});
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -361,8 +360,8 @@ void testAddResourceWithoutCapability() {
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
 		StepVerifier.create(serverWithoutResources.addResource(specification)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
-				.hasMessage("Server must be configured with resource capabilities");
+			assertThat(error).isInstanceOf(IllegalStateException.class)
+				.hasMessageContaining("Server must be configured with resource capabilities");
 		});
 	}
 
@@ -372,11 +371,184 @@ void testRemoveResourceWithoutCapability() {
 		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutResources.removeResource(TEST_RESOURCE_URI)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
-				.hasMessage("Server must be configured with resource capabilities");
+			assertThat(error).isInstanceOf(IllegalStateException.class)
+				.hasMessageContaining("Server must be configured with resource capabilities");
 		});
 	}
 
+	@Test
+	void testListResources() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
+				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier
+			.create(mcpAsyncServer.addResource(specification).then(mcpAsyncServer.listResources().collectList()))
+			.expectNextMatches(resources -> resources.size() == 1 && resources.get(0).uri().equals(TEST_RESOURCE_URI))
+			.verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResource() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
+				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier
+			.create(mcpAsyncServer.addResource(specification).then(mcpAsyncServer.removeResource(TEST_RESOURCE_URI)))
+			.verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveNonexistentResource() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource should complete successfully (no error)
+		// as per the new implementation that just logs a warning
+		StepVerifier.create(mcpAsyncServer.removeResource("nonexistent://resource")).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	// ---------------------------------------
+	// Resource Template Tests
+	// ---------------------------------------
+
+	@Test
+	void testAddResourceTemplate() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier.create(mcpAsyncServer.addResourceTemplate(specification)).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testAddResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier.create(serverWithoutResources.addResourceTemplate(specification)).verifyErrorSatisfies(error -> {
+			assertThat(error).isInstanceOf(IllegalStateException.class)
+				.hasMessageContaining("Server must be configured with resource capabilities");
+		});
+	}
+
+	@Test
+	void testRemoveResourceTemplate() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		StepVerifier.create(mcpAsyncServer.removeResourceTemplate("test://template/{id}")).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		StepVerifier.create(serverWithoutResources.removeResourceTemplate("test://template/{id}"))
+			.verifyErrorSatisfies(error -> {
+				assertThat(error).isInstanceOf(IllegalStateException.class)
+					.hasMessageContaining("Server must be configured with resource capabilities");
+			});
+	}
+
+	@Test
+	void testRemoveNonexistentResourceTemplate() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource template should complete successfully (no
+		// error)
+		// as per the new implementation that just logs a warning
+		StepVerifier.create(mcpAsyncServer.removeResourceTemplate("nonexistent://template/{id}")).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testListResourceTemplates() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		// Note: Based on the current implementation, listResourceTemplates() returns
+		// Flux
+		// This appears to be a bug in the implementation that should return
+		// Flux
+		StepVerifier.create(mcpAsyncServer.listResourceTemplates().collectList())
+			.expectNextMatches(resources -> resources.size() >= 0) // Just verify it
+																	// doesn't error
+			.verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
 	// ---------------------------------------
 	// Prompts Tests
 	// ---------------------------------------
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index cd6e8950f..3fd0f2cfb 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -1256,7 +1256,8 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 							List.of(new PromptArgument("language", "Language", "string", false))),
 					(mcpSyncServerExchange, getPromptRequest) -> null))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+					new McpSchema.PromptReference(PromptReference.TYPE, "code_review", "Code review"),
+					completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.build()) {
@@ -1265,7 +1266,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 			assertThat(initResult).isNotNull();
 
 			CompleteRequest request = new CompleteRequest(
-					new PromptReference("ref/prompt", "code_review", "Code review"),
+					new PromptReference(PromptReference.TYPE, "code_review", "Code review"),
 					new CompleteRequest.CompleteArgument("language", "py"));
 
 			CompleteResult result = mcpClient.completeCompletion(request);
@@ -1274,7 +1275,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 
 			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
 			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
-			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo(PromptReference.TYPE);
 		}
 		finally {
 			mcpServer.closeGracefully();
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index dae2e38f9..619bb7aa4 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -4,17 +4,8 @@
 
 package io.modelcontextprotocol.server;
 
-import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
 import java.util.List;
 
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
@@ -26,6 +17,14 @@
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 /**
  * Test suite for the {@link McpSyncServer} that can be used with different
@@ -335,7 +334,7 @@ void testAddResourceWithNullSpecification() {
 			.build();
 
 		assertThatThrownBy(() -> mcpSyncServer.addResource((McpServerFeatures.SyncResourceSpecification) null))
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Resource must not be null");
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
@@ -350,16 +349,184 @@ void testAddResourceWithoutCapability() {
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
-		assertThatThrownBy(() -> serverWithoutResources.addResource(specification)).isInstanceOf(McpError.class)
-			.hasMessage("Server must be configured with resource capabilities");
+		assertThatThrownBy(() -> serverWithoutResources.addResource(specification))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
 	}
 
 	@Test
 	void testRemoveResourceWithoutCapability() {
 		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI)).isInstanceOf(McpError.class)
-			.hasMessage("Server must be configured with resource capabilities");
+		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
+	}
+
+	@Test
+	void testListResources() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
+				resource, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		mcpSyncServer.addResource(specification);
+		List resources = mcpSyncServer.listResources();
+
+		assertThat(resources).hasSize(1);
+		assertThat(resources.get(0).uri()).isEqualTo(TEST_RESOURCE_URI);
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResource() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
+				resource, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		mcpSyncServer.addResource(specification);
+		assertThatCode(() -> mcpSyncServer.removeResource(TEST_RESOURCE_URI)).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveNonexistentResource() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource should complete successfully (no error)
+		// as per the new implementation that just logs a warning
+		assertThatCode(() -> mcpSyncServer.removeResource("nonexistent://resource")).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	// ---------------------------------------
+	// Resource Template Tests
+	// ---------------------------------------
+
+	@Test
+	void testAddResourceTemplate() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		assertThatCode(() -> mcpSyncServer.addResourceTemplate(specification)).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testAddResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		assertThatThrownBy(() -> serverWithoutResources.addResourceTemplate(specification))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
+	}
+
+	@Test
+	void testRemoveResourceTemplate() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("test://template/{id}")).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		assertThatThrownBy(() -> serverWithoutResources.removeResourceTemplate("test://template/{id}"))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
+	}
+
+	@Test
+	void testRemoveNonexistentResourceTemplate() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource template should complete successfully (no
+		// error)
+		// as per the new implementation that just logs a warning
+		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("nonexistent://template/{id}"))
+			.doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testListResourceTemplates() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		List templates = mcpSyncServer.listResourceTemplates();
+
+		assertThat(templates).isNotNull();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index b40f90e08..de74bafc1 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -194,7 +194,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 							List.of(new PromptArgument("language", "Language", "string", false))),
 					(transportContext, getPromptRequest) -> null))
 			.completions(new McpStatelessServerFeatures.SyncCompletionSpecification(
-					new PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+					new PromptReference(PromptReference.TYPE, "code_review", "Code review"), completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.build()) {
@@ -203,7 +203,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 			assertThat(initResult).isNotNull();
 
 			CompleteRequest request = new CompleteRequest(
-					new PromptReference("ref/prompt", "code_review", "Code review"),
+					new PromptReference(PromptReference.TYPE, "code_review", "Code review"),
 					new CompleteRequest.CompleteArgument("language", "py"));
 
 			CompleteResult result = mcpClient.completeCompletion(request);
@@ -212,7 +212,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 
 			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
 			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
-			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo(PromptReference.TYPE);
 		}
 		finally {
 			mcpServer.close();
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
index 194c37000..54fb80a78 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/McpCompletionTests.java
@@ -97,7 +97,7 @@ void testCompletionHandlerReceivesContext() {
 			return new CompleteResult(new CompleteResult.CompleteCompletion(List.of("test-completion"), 1, false));
 		};
 
-		ResourceReference resourceRef = new ResourceReference("ref/resource", "test://resource/{param}");
+		ResourceReference resourceRef = new ResourceReference(ResourceReference.TYPE, "test://resource/{param}");
 
 		var resource = Resource.builder()
 			.uri("test://resource/{param}")
@@ -152,7 +152,7 @@ void testCompletionBackwardCompatibility() {
 			.prompts(new McpServerFeatures.SyncPromptSpecification(prompt,
 					(mcpSyncServerExchange, getPromptRequest) -> null))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new PromptReference("ref/prompt", "test-prompt"), completionHandler))
+					new PromptReference(PromptReference.TYPE, "test-prompt"), completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
@@ -161,7 +161,7 @@ void testCompletionBackwardCompatibility() {
 			assertThat(initResult).isNotNull();
 
 			// Test without context
-			CompleteRequest request = new CompleteRequest(new PromptReference("ref/prompt", "test-prompt"),
+			CompleteRequest request = new CompleteRequest(new PromptReference(PromptReference.TYPE, "test-prompt"),
 					new CompleteRequest.CompleteArgument("arg", "val"));
 
 			CompleteResult result = mcpClient.completeCompletion(request);
@@ -217,7 +217,7 @@ else if ("products_db".equals(db)) {
 			.resources(new McpServerFeatures.SyncResourceSpecification(resource,
 					(exchange, req) -> new ReadResourceResult(List.of())))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new ResourceReference("ref/resource", "db://{database}/{table}"), completionHandler))
+					new ResourceReference(ResourceReference.TYPE, "db://{database}/{table}"), completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
@@ -227,7 +227,7 @@ else if ("products_db".equals(db)) {
 
 			// First, complete database
 			CompleteRequest dbRequest = new CompleteRequest(
-					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new ResourceReference(ResourceReference.TYPE, "db://{database}/{table}"),
 					new CompleteRequest.CompleteArgument("database", ""));
 
 			CompleteResult dbResult = mcpClient.completeCompletion(dbRequest);
@@ -235,7 +235,7 @@ else if ("products_db".equals(db)) {
 
 			// Then complete table with database context
 			CompleteRequest tableRequest = new CompleteRequest(
-					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new ResourceReference(ResourceReference.TYPE, "db://{database}/{table}"),
 					new CompleteRequest.CompleteArgument("table", ""),
 					new CompleteRequest.CompleteContext(Map.of("database", "users_db")));
 
@@ -244,7 +244,7 @@ else if ("products_db".equals(db)) {
 
 			// Different database gives different tables
 			CompleteRequest tableRequest2 = new CompleteRequest(
-					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new ResourceReference(ResourceReference.TYPE, "db://{database}/{table}"),
 					new CompleteRequest.CompleteArgument("table", ""),
 					new CompleteRequest.CompleteContext(Map.of("database", "products_db")));
 
@@ -294,7 +294,7 @@ void testCompletionErrorOnMissingContext() {
 			.resources(new McpServerFeatures.SyncResourceSpecification(resource,
 					(exchange, req) -> new ReadResourceResult(List.of())))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new ResourceReference("ref/resource", "db://{database}/{table}"), completionHandler))
+					new ResourceReference(ResourceReference.TYPE, "db://{database}/{table}"), completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.clientInfo(new McpSchema.Implementation("Sample" + "client", "0.0.0"))
@@ -304,7 +304,7 @@ void testCompletionErrorOnMissingContext() {
 
 			// Try to complete table without database context - should raise error
 			CompleteRequest requestWithoutContext = new CompleteRequest(
-					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new ResourceReference(ResourceReference.TYPE, "db://{database}/{table}"),
 					new CompleteRequest.CompleteArgument("table", ""));
 
 			assertThatExceptionOfType(McpError.class)
@@ -313,7 +313,7 @@ void testCompletionErrorOnMissingContext() {
 
 			// Now complete with proper context - should work normally
 			CompleteRequest requestWithContext = new CompleteRequest(
-					new ResourceReference("ref/resource", "db://{database}/{table}"),
+					new ResourceReference(ResourceReference.TYPE, "db://{database}/{table}"),
 					new CompleteRequest.CompleteArgument("table", ""),
 					new CompleteRequest.CompleteContext(Map.of("database", "test_db")));
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/ResourceTemplateManagementTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/ResourceTemplateManagementTests.java
new file mode 100644
index 000000000..b7d46a967
--- /dev/null
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/ResourceTemplateManagementTests.java
@@ -0,0 +1,299 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import java.time.Duration;
+import java.util.List;
+
+import io.modelcontextprotocol.MockMcpServerTransport;
+import io.modelcontextprotocol.MockMcpServerTransportProvider;
+import io.modelcontextprotocol.spec.McpSchema.ReadResourceResult;
+import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+
+/**
+ * Test suite for Resource Template Management functionality. Tests the new
+ * addResourceTemplate() and removeResourceTemplate() methods, as well as the Map-based
+ * resource template storage.
+ *
+ * @author Christian Tzolov
+ */
+public class ResourceTemplateManagementTests {
+
+	private static final String TEST_TEMPLATE_URI = "test://resource/{param}";
+
+	private static final String TEST_TEMPLATE_NAME = "test-template";
+
+	private MockMcpServerTransportProvider mockTransportProvider;
+
+	private McpAsyncServer mcpAsyncServer;
+
+	@BeforeEach
+	void setUp() {
+		mockTransportProvider = new MockMcpServerTransportProvider(new MockMcpServerTransport());
+	}
+
+	@AfterEach
+	void tearDown() {
+		if (mcpAsyncServer != null) {
+			assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10)))
+				.doesNotThrowAnyException();
+		}
+	}
+
+	// ---------------------------------------
+	// Async Resource Template Tests
+	// ---------------------------------------
+
+	@Test
+	void testAddResourceTemplate() {
+		mcpAsyncServer = McpServer.async(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		ResourceTemplate template = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier.create(mcpAsyncServer.addResourceTemplate(specification)).verifyComplete();
+	}
+
+	@Test
+	void testAddResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		McpAsyncServer serverWithoutResources = McpServer.async(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.build();
+
+		ResourceTemplate template = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier.create(serverWithoutResources.addResourceTemplate(specification)).verifyErrorSatisfies(error -> {
+			assertThat(error).isInstanceOf(IllegalStateException.class)
+				.hasMessageContaining("Server must be configured with resource capabilities");
+		});
+
+		assertThatCode(() -> serverWithoutResources.closeGracefully().block(Duration.ofSeconds(10)))
+			.doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResourceTemplate() {
+		ResourceTemplate template = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		mcpAsyncServer = McpServer.async(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		StepVerifier.create(mcpAsyncServer.removeResourceTemplate(TEST_TEMPLATE_URI)).verifyComplete();
+	}
+
+	@Test
+	void testRemoveResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		McpAsyncServer serverWithoutResources = McpServer.async(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.build();
+
+		StepVerifier.create(serverWithoutResources.removeResourceTemplate(TEST_TEMPLATE_URI))
+			.verifyErrorSatisfies(error -> {
+				assertThat(error).isInstanceOf(IllegalStateException.class)
+					.hasMessageContaining("Server must be configured with resource capabilities");
+			});
+
+		assertThatCode(() -> serverWithoutResources.closeGracefully().block(Duration.ofSeconds(10)))
+			.doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveNonexistentResourceTemplate() {
+		mcpAsyncServer = McpServer.async(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource template should complete successfully (no
+		// error)
+		// as per the new implementation that just logs a warning
+		StepVerifier.create(mcpAsyncServer.removeResourceTemplate("nonexistent://template/{id}")).verifyComplete();
+	}
+
+	@Test
+	void testReplaceExistingResourceTemplate() {
+		ResourceTemplate originalTemplate = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Original template")
+			.mimeType("text/plain")
+			.build();
+
+		ResourceTemplate updatedTemplate = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Updated template")
+			.mimeType("application/json")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification originalSpec = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				originalTemplate, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		McpServerFeatures.AsyncResourceTemplateSpecification updatedSpec = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				updatedTemplate, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		mcpAsyncServer = McpServer.async(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(originalSpec)
+			.build();
+
+		// Adding a resource template with the same URI should replace the existing one
+		StepVerifier.create(mcpAsyncServer.addResourceTemplate(updatedSpec)).verifyComplete();
+	}
+
+	// ---------------------------------------
+	// Sync Resource Template Tests
+	// ---------------------------------------
+
+	@Test
+	void testSyncAddResourceTemplate() {
+		ResourceTemplate template = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		var mcpSyncServer = McpServer.sync(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		assertThatCode(() -> mcpSyncServer.addResourceTemplate(specification)).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testSyncRemoveResourceTemplate() {
+		ResourceTemplate template = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		var mcpSyncServer = McpServer.sync(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		assertThatCode(() -> mcpSyncServer.removeResourceTemplate(TEST_TEMPLATE_URI)).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	// ---------------------------------------
+	// Map-based Storage Tests
+	// ---------------------------------------
+
+	@Test
+	void testResourceTemplateMapBasedStorage() {
+		ResourceTemplate template1 = ResourceTemplate.builder()
+			.uriTemplate("test://template1/{id}")
+			.name("template1")
+			.description("First template")
+			.mimeType("text/plain")
+			.build();
+
+		ResourceTemplate template2 = ResourceTemplate.builder()
+			.uriTemplate("test://template2/{id}")
+			.name("template2")
+			.description("Second template")
+			.mimeType("application/json")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification spec1 = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template1, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		McpServerFeatures.AsyncResourceTemplateSpecification spec2 = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template2, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		mcpAsyncServer = McpServer.async(mockTransportProvider)
+			.serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(spec1, spec2)
+			.build();
+
+		// Verify both templates are stored (this would be tested through integration
+		// tests
+		// or by accessing internal state, but for unit tests we verify no exceptions)
+		assertThat(mcpAsyncServer).isNotNull();
+	}
+
+	@Test
+	void testResourceTemplateBuilderWithMap() {
+		// Test that the new Map-based builder methods work correctly
+		ResourceTemplate template = ResourceTemplate.builder()
+			.uriTemplate(TEST_TEMPLATE_URI)
+			.name(TEST_TEMPLATE_NAME)
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		// Test varargs builder method
+		assertThatCode(() -> {
+			McpServer.async(mockTransportProvider)
+				.serverInfo("test-server", "1.0.0")
+				.capabilities(ServerCapabilities.builder().resources(true, false).build())
+				.resourceTemplates(specification)
+				.build()
+				.closeGracefully()
+				.block(Duration.ofSeconds(10));
+		}).doesNotThrowAnyException();
+	}
+
+}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
index 25e22f968..382cda1ce 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.spec;
 
+import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import org.junit.jupiter.api.Test;
 
 import static org.junit.jupiter.api.Assertions.*;
@@ -15,8 +16,10 @@ class PromptReferenceEqualsTest {
 
 	@Test
 	void testEqualsWithSameIdentifierAndType() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
-		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Different Title");
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Test Title");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Different Title");
 
 		assertTrue(ref1.equals(ref2), "PromptReferences with same identifier and type should be equal");
 		assertEquals(ref1.hashCode(), ref2.hashCode(), "Equal objects should have same hash code");
@@ -24,15 +27,18 @@ void testEqualsWithSameIdentifierAndType() {
 
 	@Test
 	void testEqualsWithDifferentIdentifier() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt-1", "Test Title");
-		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt-2", "Test Title");
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt-1",
+				"Test Title");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt-2",
+				"Test Title");
 
 		assertFalse(ref1.equals(ref2), "PromptReferences with different identifiers should not be equal");
 	}
 
 	@Test
 	void testEqualsWithDifferentType() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Test Title");
 		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/other", "test-prompt", "Test Title");
 
 		assertFalse(ref1.equals(ref2), "PromptReferences with different types should not be equal");
@@ -40,14 +46,16 @@ void testEqualsWithDifferentType() {
 
 	@Test
 	void testEqualsWithNull() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Test Title");
 
 		assertFalse(ref1.equals(null), "PromptReference should not be equal to null");
 	}
 
 	@Test
 	void testEqualsWithDifferentClass() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Test Title");
 		String other = "not a PromptReference";
 
 		assertFalse(ref1.equals(other), "PromptReference should not be equal to different class");
@@ -55,16 +63,17 @@ void testEqualsWithDifferentClass() {
 
 	@Test
 	void testEqualsWithSameInstance() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Test Title");
 
 		assertTrue(ref1.equals(ref1), "PromptReference should be equal to itself");
 	}
 
 	@Test
 	void testEqualsIgnoresTitle() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Title 1");
-		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Title 2");
-		McpSchema.PromptReference ref3 = new McpSchema.PromptReference("ref/prompt", "test-prompt", null);
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt", "Title 1");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt", "Title 2");
+		McpSchema.PromptReference ref3 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt", null);
 
 		assertTrue(ref1.equals(ref2), "PromptReferences should be equal regardless of title");
 		assertTrue(ref1.equals(ref3), "PromptReferences should be equal even when one has null title");
@@ -73,8 +82,10 @@ void testEqualsIgnoresTitle() {
 
 	@Test
 	void testHashCodeConsistency() {
-		McpSchema.PromptReference ref1 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Test Title");
-		McpSchema.PromptReference ref2 = new McpSchema.PromptReference("ref/prompt", "test-prompt", "Different Title");
+		McpSchema.PromptReference ref1 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Test Title");
+		McpSchema.PromptReference ref2 = new McpSchema.PromptReference(PromptReference.TYPE, "test-prompt",
+				"Different Title");
 
 		assertEquals(ref1.hashCode(), ref2.hashCode(), "Objects that are equal should have the same hash code");
 
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 84bd271a5..1b34c43a7 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -1260,7 +1260,8 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 							List.of(new PromptArgument("language", "Language", "string", false))),
 					(mcpSyncServerExchange, getPromptRequest) -> null))
 			.completions(new McpServerFeatures.SyncCompletionSpecification(
-					new McpSchema.PromptReference("ref/prompt", "code_review", "Code review"), completionHandler))
+					new McpSchema.PromptReference(PromptReference.TYPE, "code_review", "Code review"),
+					completionHandler))
 			.build();
 
 		try (var mcpClient = clientBuilder.build()) {
@@ -1269,7 +1270,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 			assertThat(initResult).isNotNull();
 
 			CompleteRequest request = new CompleteRequest(
-					new PromptReference("ref/prompt", "code_review", "Code review"),
+					new PromptReference(PromptReference.TYPE, "code_review", "Code review"),
 					new CompleteRequest.CompleteArgument("language", "py"));
 
 			CompleteResult result = mcpClient.completeCompletion(request);
@@ -1278,7 +1279,7 @@ void testCompletionShouldReturnExpectedSuggestions(String clientType) {
 
 			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
 			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
-			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo(PromptReference.TYPE);
 		}
 		finally {
 			mcpServer.closeGracefully();
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index ed7f2c3ce..4c4e49dc5 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -99,7 +99,11 @@ void testImmediateClose() {
 	@Test
 	@Deprecated
 	void testAddTool() {
-		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
@@ -113,7 +117,12 @@ void testAddTool() {
 
 	@Test
 	void testAddToolCall() {
-		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
+
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
@@ -198,6 +207,7 @@ void testDuplicateToolsInBatchListRegistration() {
 			.title("Duplicate tool in batch list")
 			.inputSchema(EMPTY_JSON_SCHEMA)
 			.build();
+
 		List specs = List.of(
 				McpServerFeatures.AsyncToolSpecification.builder()
 					.tool(duplicateTool)
@@ -246,6 +256,7 @@ void testRemoveTool() {
 			.title("Duplicate tool")
 			.inputSchema(EMPTY_JSON_SCHEMA)
 			.build();
+
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
@@ -336,7 +347,7 @@ void testAddResourceWithNullSpecification() {
 
 		StepVerifier.create(mcpAsyncServer.addResource((McpServerFeatures.AsyncResourceSpecification) null))
 			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class).hasMessage("Resource must not be null");
+				assertThat(error).isInstanceOf(IllegalArgumentException.class).hasMessage("Resource must not be null");
 			});
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -353,8 +364,8 @@ void testAddResourceWithoutCapability() {
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
 		StepVerifier.create(serverWithoutResources.addResource(specification)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
-				.hasMessage("Server must be configured with resource capabilities");
+			assertThat(error).isInstanceOf(IllegalStateException.class)
+				.hasMessageContaining("Server must be configured with resource capabilities");
 		});
 	}
 
@@ -364,11 +375,184 @@ void testRemoveResourceWithoutCapability() {
 		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutResources.removeResource(TEST_RESOURCE_URI)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
-				.hasMessage("Server must be configured with resource capabilities");
+			assertThat(error).isInstanceOf(IllegalStateException.class)
+				.hasMessageContaining("Server must be configured with resource capabilities");
 		});
 	}
 
+	@Test
+	void testListResources() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
+				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier
+			.create(mcpAsyncServer.addResource(specification).then(mcpAsyncServer.listResources().collectList()))
+			.expectNextMatches(resources -> resources.size() == 1 && resources.get(0).uri().equals(TEST_RESOURCE_URI))
+			.verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResource() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
+				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier
+			.create(mcpAsyncServer.addResource(specification).then(mcpAsyncServer.removeResource(TEST_RESOURCE_URI)))
+			.verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveNonexistentResource() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource should complete successfully (no error)
+		// as per the new implementation that just logs a warning
+		StepVerifier.create(mcpAsyncServer.removeResource("nonexistent://resource")).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	// ---------------------------------------
+	// Resource Template Tests
+	// ---------------------------------------
+
+	@Test
+	void testAddResourceTemplate() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier.create(mcpAsyncServer.addResourceTemplate(specification)).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testAddResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		StepVerifier.create(serverWithoutResources.addResourceTemplate(specification)).verifyErrorSatisfies(error -> {
+			assertThat(error).isInstanceOf(IllegalStateException.class)
+				.hasMessageContaining("Server must be configured with resource capabilities");
+		});
+	}
+
+	@Test
+	void testRemoveResourceTemplate() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		StepVerifier.create(mcpAsyncServer.removeResourceTemplate("test://template/{id}")).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		StepVerifier.create(serverWithoutResources.removeResourceTemplate("test://template/{id}"))
+			.verifyErrorSatisfies(error -> {
+				assertThat(error).isInstanceOf(IllegalStateException.class)
+					.hasMessageContaining("Server must be configured with resource capabilities");
+			});
+	}
+
+	@Test
+	void testRemoveNonexistentResourceTemplate() {
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource template should complete successfully (no
+		// error)
+		// as per the new implementation that just logs a warning
+		StepVerifier.create(mcpAsyncServer.removeResourceTemplate("nonexistent://template/{id}")).verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testListResourceTemplates() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.AsyncResourceTemplateSpecification specification = new McpServerFeatures.AsyncResourceTemplateSpecification(
+				template, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
+
+		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		// Note: Based on the current implementation, listResourceTemplates() returns
+		// Flux
+		// This appears to be a bug in the implementation that should return
+		// Flux
+		StepVerifier.create(mcpAsyncServer.listResourceTemplates().collectList())
+			.expectNextMatches(resources -> resources.size() >= 0) // Just verify it
+																	// doesn't error
+			.verifyComplete();
+
+		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
+	}
+
 	// ---------------------------------------
 	// Prompts Tests
 	// ---------------------------------------
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index d7b1dab2a..ff37abd74 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -4,18 +4,8 @@
 
 package io.modelcontextprotocol.server;
 
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
-
 import java.util.List;
 
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-
-import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
-
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
@@ -27,6 +17,14 @@
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static io.modelcontextprotocol.util.ToolsUtils.EMPTY_JSON_SCHEMA;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 /**
  * Test suite for the {@link McpSyncServer} that can be used with different
@@ -101,6 +99,7 @@ void testGetAsyncServer() {
 	// ---------------------------------------
 	// Tools Tests
 	// ---------------------------------------
+
 	@Test
 	@Deprecated
 	void testAddTool() {
@@ -108,7 +107,11 @@ void testAddTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(newTool,
 				(exchange, args) -> new CallToolResult(List.of(), false))))
 			.doesNotThrowAnyException();
@@ -122,7 +125,12 @@ void testAddToolCall() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		Tool newTool = Tool.builder().name("new-tool").title("New test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
+		Tool newTool = McpSchema.Tool.builder()
+			.name("new-tool")
+			.title("New test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
+
 		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(newTool)
 			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
@@ -134,7 +142,7 @@ void testAddToolCall() {
 	@Test
 	@Deprecated
 	void testAddDuplicateTool() {
-		Tool duplicateTool = Tool.builder()
+		Tool duplicateTool = McpSchema.Tool.builder()
 			.name(TEST_TOOL_NAME)
 			.title("Duplicate tool")
 			.inputSchema(EMPTY_JSON_SCHEMA)
@@ -155,7 +163,7 @@ void testAddDuplicateTool() {
 
 	@Test
 	void testAddDuplicateToolCall() {
-		Tool duplicateTool = Tool.builder()
+		Tool duplicateTool = McpSchema.Tool.builder()
 			.name(TEST_TOOL_NAME)
 			.title("Duplicate tool")
 			.inputSchema(EMPTY_JSON_SCHEMA)
@@ -177,7 +185,7 @@ void testAddDuplicateToolCall() {
 
 	@Test
 	void testDuplicateToolCallDuringBuilding() {
-		Tool duplicateTool = Tool.builder()
+		Tool duplicateTool = McpSchema.Tool.builder()
 			.name("duplicate-build-toolcall")
 			.title("Duplicate toolcall during building")
 			.inputSchema(EMPTY_JSON_SCHEMA)
@@ -193,7 +201,7 @@ void testDuplicateToolCallDuringBuilding() {
 
 	@Test
 	void testDuplicateToolsInBatchListRegistration() {
-		Tool duplicateTool = Tool.builder()
+		Tool duplicateTool = McpSchema.Tool.builder()
 			.name("batch-list-tool")
 			.title("Duplicate tool in batch list")
 			.inputSchema(EMPTY_JSON_SCHEMA)
@@ -218,7 +226,7 @@ void testDuplicateToolsInBatchListRegistration() {
 
 	@Test
 	void testDuplicateToolsInBatchVarargsRegistration() {
-		Tool duplicateTool = Tool.builder()
+		Tool duplicateTool = McpSchema.Tool.builder()
 			.name("batch-varargs-tool")
 			.title("Duplicate tool in batch varargs")
 			.inputSchema(EMPTY_JSON_SCHEMA)
@@ -241,7 +249,11 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 
 	@Test
 	void testRemoveTool() {
-		Tool tool = Tool.builder().name(TEST_TOOL_NAME).title("Test tool").inputSchema(EMPTY_JSON_SCHEMA).build();
+		Tool tool = McpSchema.Tool.builder()
+			.name(TEST_TOOL_NAME)
+			.title("Test tool")
+			.inputSchema(EMPTY_JSON_SCHEMA)
+			.build();
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
@@ -321,7 +333,7 @@ void testAddResourceWithNullSpecification() {
 			.build();
 
 		assertThatThrownBy(() -> mcpSyncServer.addResource((McpServerFeatures.SyncResourceSpecification) null))
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Resource must not be null");
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
@@ -336,16 +348,184 @@ void testAddResourceWithoutCapability() {
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
-		assertThatThrownBy(() -> serverWithoutResources.addResource(specification)).isInstanceOf(McpError.class)
-			.hasMessage("Server must be configured with resource capabilities");
+		assertThatThrownBy(() -> serverWithoutResources.addResource(specification))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
 	}
 
 	@Test
 	void testRemoveResourceWithoutCapability() {
 		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI)).isInstanceOf(McpError.class)
-			.hasMessage("Server must be configured with resource capabilities");
+		assertThatThrownBy(() -> serverWithoutResources.removeResource(TEST_RESOURCE_URI))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
+	}
+
+	@Test
+	void testListResources() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
+				resource, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		mcpSyncServer.addResource(specification);
+		List resources = mcpSyncServer.listResources();
+
+		assertThat(resources).hasSize(1);
+		assertThat(resources.get(0).uri()).isEqualTo(TEST_RESOURCE_URI);
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResource() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
+				null);
+		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
+				resource, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		mcpSyncServer.addResource(specification);
+		assertThatCode(() -> mcpSyncServer.removeResource(TEST_RESOURCE_URI)).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveNonexistentResource() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource should complete successfully (no error)
+		// as per the new implementation that just logs a warning
+		assertThatCode(() -> mcpSyncServer.removeResource("nonexistent://resource")).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	// ---------------------------------------
+	// Resource Template Tests
+	// ---------------------------------------
+
+	@Test
+	void testAddResourceTemplate() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		assertThatCode(() -> mcpSyncServer.addResourceTemplate(specification)).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testAddResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		assertThatThrownBy(() -> serverWithoutResources.addResourceTemplate(specification))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
+	}
+
+	@Test
+	void testRemoveResourceTemplate() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("test://template/{id}")).doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testRemoveResourceTemplateWithoutCapability() {
+		// Create a server without resource capabilities
+		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
+
+		assertThatThrownBy(() -> serverWithoutResources.removeResourceTemplate("test://template/{id}"))
+			.isInstanceOf(IllegalStateException.class)
+			.hasMessageContaining("Server must be configured with resource capabilities");
+	}
+
+	@Test
+	void testRemoveNonexistentResourceTemplate() {
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.build();
+
+		// Removing a non-existent resource template should complete successfully (no
+		// error)
+		// as per the new implementation that just logs a warning
+		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("nonexistent://template/{id}"))
+			.doesNotThrowAnyException();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+	}
+
+	@Test
+	void testListResourceTemplates() {
+		McpSchema.ResourceTemplate template = McpSchema.ResourceTemplate.builder()
+			.uriTemplate("test://template/{id}")
+			.name("test-template")
+			.description("Test resource template")
+			.mimeType("text/plain")
+			.build();
+
+		McpServerFeatures.SyncResourceTemplateSpecification specification = new McpServerFeatures.SyncResourceTemplateSpecification(
+				template, (exchange, req) -> new ReadResourceResult(List.of()));
+
+		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
+			.capabilities(ServerCapabilities.builder().resources(true, false).build())
+			.resourceTemplates(specification)
+			.build();
+
+		List templates = mcpSyncServer.listResourceTemplates();
+
+		assertThat(templates).isNotNull();
+
+		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -440,7 +620,6 @@ void testRootsChangeHandlers() {
 				}
 			}))
 			.build();
-
 		assertThat(singleConsumerServer).isNotNull();
 		assertThatCode(() -> singleConsumerServer.closeGracefully()).doesNotThrowAnyException();
 		onClose();

From c1cde20002039a984321489c125cbc48d8a04a8e Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Tue, 30 Sep 2025 11:10:04 +0200
Subject: [PATCH 083/125] refactor: improve MCP server resilience and error
 handling (#579)

- Replace McpError with appropriate standard exceptions (IllegalArgumentException, IllegalStateException) for validation errors
- Change tool/prompt registration to replace existing items instead of rejecting duplicates with warningsi
  - Change addTool behavior to replace existing tools instead of throwing errors
  - Change addPrompt() to allow replacing existing prompts with warning instead of throwing error
- Make removal operations idempotent - log warnings instead of throwing errors for non-existent items
  - Change removePrompt() to log warning instead of throwing error for non-existent prompts
  - Change removeTool() to gracefully handle non-existent tools with warnings instead of errors
- Add listTools() and listPrompts() methods to all server variants (async, sync, stateless)
  - Add listTools() method to all server classes for tool enumeration
  - Add listPrompts() method to all server implementations for retrieving registered prompts
- Improve error construction using McpError.builder() pattern for protocol-specific errors
- Update error handling in session classes to properly propagate McpError JSON-RPC errors
  - Use proper error codes (INVALID_PARAMS) for prompt not found scenarios
- Update tests to reflect new lenient behavior for duplicate registrations and removals
- Add aggregateExceptionMessages() utility method utility to aggregate the exception chains
- Update McpServerSession and McpStreamableServerSession to use the aggregated errors in the json-rpc-error data section

This change makes the MCP server APIs more resilient and user-friendly by using appropriate exception types,
supporting item replacement, and providing listing capabilities while maintaining backward compatibility.

Signed-off-by: Christian Tzolov 
---
 .../server/McpAsyncServer.java                | 94 +++++++++++--------
 .../server/McpStatelessAsyncServer.java       | 86 +++++++++++------
 .../server/McpStatelessSyncServer.java        | 16 ++++
 .../server/McpSyncServer.java                 | 16 ++++
 .../modelcontextprotocol/spec/McpError.java   | 41 +++++++-
 .../spec/McpServerSession.java                | 20 ++--
 .../spec/McpStreamableServerSession.java      |  8 +-
 .../server/AbstractMcpAsyncServerTests.java   | 34 ++-----
 ...stractMcpClientServerIntegrationTests.java | 49 ++++++----
 .../server/AbstractMcpSyncServerTests.java    | 27 +++---
 ...stractMcpClientServerIntegrationTests.java | 49 ++++++----
 .../server/AbstractMcpAsyncServerTests.java   | 34 ++-----
 .../server/AbstractMcpSyncServerTests.java    | 27 +++---
 13 files changed, 305 insertions(+), 196 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index c07fdf2af..dcba3af1f 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -322,25 +322,24 @@ private McpNotificationHandler asyncRootsListChangedNotificationHandler(
 	 */
 	public Mono addTool(McpServerFeatures.AsyncToolSpecification toolSpecification) {
 		if (toolSpecification == null) {
-			return Mono.error(new McpError("Tool specification must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool specification must not be null"));
 		}
 		if (toolSpecification.tool() == null) {
-			return Mono.error(new McpError("Tool must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool must not be null"));
 		}
 		if (toolSpecification.call() == null && toolSpecification.callHandler() == null) {
-			return Mono.error(new McpError("Tool call handler must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool call handler must not be null"));
 		}
 		if (this.serverCapabilities.tools() == null) {
-			return Mono.error(new McpError("Server must be configured with tool capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with tool capabilities"));
 		}
 
 		var wrappedToolSpecification = withStructuredOutputHandling(this.jsonSchemaValidator, toolSpecification);
 
 		return Mono.defer(() -> {
-			// Check for duplicate tool names
-			if (this.tools.stream().anyMatch(th -> th.tool().name().equals(wrappedToolSpecification.tool().name()))) {
-				return Mono.error(
-						new McpError("Tool with name '" + wrappedToolSpecification.tool().name() + "' already exists"));
+			// Remove tools with duplicate tool names first
+			if (this.tools.removeIf(th -> th.tool().name().equals(wrappedToolSpecification.tool().name()))) {
+				logger.warn("Replace existing Tool with name '{}'", wrappedToolSpecification.tool().name());
 			}
 
 			this.tools.add(wrappedToolSpecification);
@@ -464,6 +463,14 @@ private static McpServerFeatures.AsyncToolSpecification withStructuredOutputHand
 			.build();
 	}
 
+	/**
+	 * List all registered tools.
+	 * @return A Flux stream of all registered tools
+	 */
+	public Flux listTools() {
+		return Flux.fromIterable(this.tools).map(McpServerFeatures.AsyncToolSpecification::tool);
+	}
+
 	/**
 	 * Remove a tool handler at runtime.
 	 * @param toolName The name of the tool handler to remove
@@ -471,23 +478,25 @@ private static McpServerFeatures.AsyncToolSpecification withStructuredOutputHand
 	 */
 	public Mono removeTool(String toolName) {
 		if (toolName == null) {
-			return Mono.error(new McpError("Tool name must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool name must not be null"));
 		}
 		if (this.serverCapabilities.tools() == null) {
-			return Mono.error(new McpError("Server must be configured with tool capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with tool capabilities"));
 		}
 
 		return Mono.defer(() -> {
-			boolean removed = this.tools
-				.removeIf(toolSpecification -> toolSpecification.tool().name().equals(toolName));
-			if (removed) {
+			if (this.tools.removeIf(toolSpecification -> toolSpecification.tool().name().equals(toolName))) {
+
 				logger.debug("Removed tool handler: {}", toolName);
 				if (this.serverCapabilities.tools().listChanged()) {
 					return notifyToolsListChanged();
 				}
-				return Mono.empty();
 			}
-			return Mono.error(new McpError("Tool with name '" + toolName + "' not found"));
+			else {
+				logger.warn("Ignore as a Tool with name '{}' not found", toolName);
+			}
+
+			return Mono.empty();
 		});
 	}
 
@@ -518,8 +527,10 @@ private McpRequestHandler toolsCallRequestHandler() {
 				.findAny();
 
 			if (toolSpecification.isEmpty()) {
-				return Mono.error(new McpError(new JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INVALID_PARAMS,
-						"Unknown tool: invalid_tool_name", "Tool not found: " + callToolRequest.name())));
+				return Mono.error(McpError.builder(McpSchema.ErrorCodes.INVALID_PARAMS)
+					.message("Unknown tool: invalid_tool_name")
+					.data("Tool not found: " + callToolRequest.name())
+					.build());
 			}
 
 			return toolSpecification.get().callHandler().apply(exchange, callToolRequest);
@@ -747,32 +758,36 @@ private Optional findResou
 	 */
 	public Mono addPrompt(McpServerFeatures.AsyncPromptSpecification promptSpecification) {
 		if (promptSpecification == null) {
-			return Mono.error(new McpError("Prompt specification must not be null"));
+			return Mono.error(new IllegalArgumentException("Prompt specification must not be null"));
 		}
 		if (this.serverCapabilities.prompts() == null) {
-			return Mono.error(new McpError("Server must be configured with prompt capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with prompt capabilities"));
 		}
 
 		return Mono.defer(() -> {
-			McpServerFeatures.AsyncPromptSpecification specification = this.prompts
-				.putIfAbsent(promptSpecification.prompt().name(), promptSpecification);
-			if (specification != null) {
-				return Mono.error(
-						new McpError("Prompt with name '" + promptSpecification.prompt().name() + "' already exists"));
+			var previous = this.prompts.put(promptSpecification.prompt().name(), promptSpecification);
+			if (previous != null) {
+				logger.warn("Replace existing Prompt with name '{}'", promptSpecification.prompt().name());
+			}
+			else {
+				logger.debug("Added prompt handler: {}", promptSpecification.prompt().name());
 			}
-
-			logger.debug("Added prompt handler: {}", promptSpecification.prompt().name());
-
-			// Servers that declared the listChanged capability SHOULD send a
-			// notification,
-			// when the list of available prompts changes
 			if (this.serverCapabilities.prompts().listChanged()) {
-				return notifyPromptsListChanged();
+				return this.notifyPromptsListChanged();
 			}
+
 			return Mono.empty();
 		});
 	}
 
+	/**
+	 * List all registered prompts.
+	 * @return A Flux stream of all registered prompts
+	 */
+	public Flux listPrompts() {
+		return Flux.fromIterable(this.prompts.values()).map(McpServerFeatures.AsyncPromptSpecification::prompt);
+	}
+
 	/**
 	 * Remove a prompt handler at runtime.
 	 * @param promptName The name of the prompt handler to remove
@@ -780,10 +795,10 @@ public Mono addPrompt(McpServerFeatures.AsyncPromptSpecification promptSpe
 	 */
 	public Mono removePrompt(String promptName) {
 		if (promptName == null) {
-			return Mono.error(new McpError("Prompt name must not be null"));
+			return Mono.error(new IllegalArgumentException("Prompt name must not be null"));
 		}
 		if (this.serverCapabilities.prompts() == null) {
-			return Mono.error(new McpError("Server must be configured with prompt capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with prompt capabilities"));
 		}
 
 		return Mono.defer(() -> {
@@ -791,14 +806,15 @@ public Mono removePrompt(String promptName) {
 
 			if (removed != null) {
 				logger.debug("Removed prompt handler: {}", promptName);
-				// Servers that declared the listChanged capability SHOULD send a
-				// notification, when the list of available prompts changes
 				if (this.serverCapabilities.prompts().listChanged()) {
 					return this.notifyPromptsListChanged();
 				}
 				return Mono.empty();
 			}
-			return Mono.error(new McpError("Prompt with name '" + promptName + "' not found"));
+			else {
+				logger.warn("Ignore as a Prompt with name '{}' not found", promptName);
+			}
+			return Mono.empty();
 		});
 	}
 
@@ -834,8 +850,12 @@ private McpRequestHandler promptsGetRequestHandler()
 
 			// Implement prompt retrieval logic here
 			McpServerFeatures.AsyncPromptSpecification specification = this.prompts.get(promptRequest.name());
+
 			if (specification == null) {
-				return Mono.error(new McpError("Prompt not found: " + promptRequest.name()));
+				return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+					.message("Invalid prompt name")
+					.data("Prompt not found: " + promptRequest.name())
+					.build());
 			}
 
 			return Mono.defer(() -> specification.promptHandler().apply(exchange, promptRequest));
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 81b50eb2e..823aca41d 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -319,25 +319,24 @@ public Mono apply(McpTransportContext transportContext, McpSchem
 	 */
 	public Mono addTool(McpStatelessServerFeatures.AsyncToolSpecification toolSpecification) {
 		if (toolSpecification == null) {
-			return Mono.error(new McpError("Tool specification must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool specification must not be null"));
 		}
 		if (toolSpecification.tool() == null) {
-			return Mono.error(new McpError("Tool must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool must not be null"));
 		}
 		if (toolSpecification.callHandler() == null) {
-			return Mono.error(new McpError("Tool call handler must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool call handler must not be null"));
 		}
 		if (this.serverCapabilities.tools() == null) {
-			return Mono.error(new McpError("Server must be configured with tool capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with tool capabilities"));
 		}
 
 		var wrappedToolSpecification = withStructuredOutputHandling(this.jsonSchemaValidator, toolSpecification);
 
 		return Mono.defer(() -> {
-			// Check for duplicate tool names
-			if (this.tools.stream().anyMatch(th -> th.tool().name().equals(wrappedToolSpecification.tool().name()))) {
-				return Mono.error(
-						new McpError("Tool with name '" + wrappedToolSpecification.tool().name() + "' already exists"));
+			// Remove tools with duplicate tool names first
+			if (this.tools.removeIf(th -> th.tool().name().equals(wrappedToolSpecification.tool().name()))) {
+				logger.warn("Replace existing Tool with name '{}'", wrappedToolSpecification.tool().name());
 			}
 
 			this.tools.add(wrappedToolSpecification);
@@ -347,6 +346,14 @@ public Mono addTool(McpStatelessServerFeatures.AsyncToolSpecification tool
 		});
 	}
 
+	/**
+	 * List all registered tools.
+	 * @return A Flux stream of all registered tools
+	 */
+	public Flux listTools() {
+		return Flux.fromIterable(this.tools).map(McpStatelessServerFeatures.AsyncToolSpecification::tool);
+	}
+
 	/**
 	 * Remove a tool handler at runtime.
 	 * @param toolName The name of the tool handler to remove
@@ -354,20 +361,22 @@ public Mono addTool(McpStatelessServerFeatures.AsyncToolSpecification tool
 	 */
 	public Mono removeTool(String toolName) {
 		if (toolName == null) {
-			return Mono.error(new McpError("Tool name must not be null"));
+			return Mono.error(new IllegalArgumentException("Tool name must not be null"));
 		}
 		if (this.serverCapabilities.tools() == null) {
-			return Mono.error(new McpError("Server must be configured with tool capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with tool capabilities"));
 		}
 
 		return Mono.defer(() -> {
-			boolean removed = this.tools
-				.removeIf(toolSpecification -> toolSpecification.tool().name().equals(toolName));
-			if (removed) {
+			if (this.tools.removeIf(toolSpecification -> toolSpecification.tool().name().equals(toolName))) {
+
 				logger.debug("Removed tool handler: {}", toolName);
-				return Mono.empty();
 			}
-			return Mono.error(new McpError("Tool with name '" + toolName + "' not found"));
+			else {
+				logger.warn("Ignore as a Tool with name '{}' not found", toolName);
+			}
+
+			return Mono.empty();
 		});
 	}
 
@@ -391,8 +400,10 @@ private McpStatelessRequestHandler toolsCallRequestHandler() {
 				.findAny();
 
 			if (toolSpecification.isEmpty()) {
-				return Mono.error(new McpError(new JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INVALID_PARAMS,
-						"Unknown tool: invalid_tool_name", "Tool not found: " + callToolRequest.name())));
+				return Mono.error(McpError.builder(McpSchema.ErrorCodes.INVALID_PARAMS)
+					.message("Unknown tool: invalid_tool_name")
+					.data("Tool not found: " + callToolRequest.name())
+					.build());
 			}
 
 			return toolSpecification.get().callHandler().apply(ctx, callToolRequest);
@@ -593,26 +604,34 @@ private Optional
 	 */
 	public Mono addPrompt(McpStatelessServerFeatures.AsyncPromptSpecification promptSpecification) {
 		if (promptSpecification == null) {
-			return Mono.error(new McpError("Prompt specification must not be null"));
+			return Mono.error(new IllegalArgumentException("Prompt specification must not be null"));
 		}
 		if (this.serverCapabilities.prompts() == null) {
-			return Mono.error(new McpError("Server must be configured with prompt capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with prompt capabilities"));
 		}
 
 		return Mono.defer(() -> {
-			McpStatelessServerFeatures.AsyncPromptSpecification specification = this.prompts
-				.putIfAbsent(promptSpecification.prompt().name(), promptSpecification);
-			if (specification != null) {
-				return Mono.error(
-						new McpError("Prompt with name '" + promptSpecification.prompt().name() + "' already exists"));
+			var previous = this.prompts.put(promptSpecification.prompt().name(), promptSpecification);
+			if (previous != null) {
+				logger.warn("Replace existing Prompt with name '{}'", promptSpecification.prompt().name());
+			}
+			else {
+				logger.debug("Added prompt handler: {}", promptSpecification.prompt().name());
 			}
-
-			logger.debug("Added prompt handler: {}", promptSpecification.prompt().name());
 
 			return Mono.empty();
 		});
 	}
 
+	/**
+	 * List all registered prompts.
+	 * @return A Flux stream of all registered prompts
+	 */
+	public Flux listPrompts() {
+		return Flux.fromIterable(this.prompts.values())
+			.map(McpStatelessServerFeatures.AsyncPromptSpecification::prompt);
+	}
+
 	/**
 	 * Remove a prompt handler at runtime.
 	 * @param promptName The name of the prompt handler to remove
@@ -620,10 +639,10 @@ public Mono addPrompt(McpStatelessServerFeatures.AsyncPromptSpecification
 	 */
 	public Mono removePrompt(String promptName) {
 		if (promptName == null) {
-			return Mono.error(new McpError("Prompt name must not be null"));
+			return Mono.error(new IllegalArgumentException("Prompt name must not be null"));
 		}
 		if (this.serverCapabilities.prompts() == null) {
-			return Mono.error(new McpError("Server must be configured with prompt capabilities"));
+			return Mono.error(new IllegalStateException("Server must be configured with prompt capabilities"));
 		}
 
 		return Mono.defer(() -> {
@@ -633,7 +652,11 @@ public Mono removePrompt(String promptName) {
 				logger.debug("Removed prompt handler: {}", promptName);
 				return Mono.empty();
 			}
-			return Mono.error(new McpError("Prompt with name '" + promptName + "' not found"));
+			else {
+				logger.warn("Ignore as a Prompt with name '{}' not found", promptName);
+			}
+
+			return Mono.empty();
 		});
 	}
 
@@ -662,7 +685,10 @@ private McpStatelessRequestHandler promptsGetRequestH
 			// Implement prompt retrieval logic here
 			McpStatelessServerFeatures.AsyncPromptSpecification specification = this.prompts.get(promptRequest.name());
 			if (specification == null) {
-				return Mono.error(new McpError("Prompt not found: " + promptRequest.name()));
+				return Mono.error(McpError.builder(ErrorCodes.INVALID_PARAMS)
+					.message("Invalid prompt name")
+					.data("Prompt not found: " + promptRequest.name())
+					.build());
 			}
 
 			return specification.promptHandler().apply(ctx, promptRequest);
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
index 65833d135..6849eb8ed 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java
@@ -74,6 +74,14 @@ public void addTool(McpStatelessServerFeatures.SyncToolSpecification toolSpecifi
 			.block();
 	}
 
+	/**
+	 * List all registered tools.
+	 * @return A list of all registered tools
+	 */
+	public List listTools() {
+		return this.asyncServer.listTools().collectList().block();
+	}
+
 	/**
 	 * Remove a tool handler at runtime.
 	 * @param toolName The name of the tool handler to remove
@@ -148,6 +156,14 @@ public void addPrompt(McpStatelessServerFeatures.SyncPromptSpecification promptS
 			.block();
 	}
 
+	/**
+	 * List all registered prompts.
+	 * @return A list of all registered prompts
+	 */
+	public List listPrompts() {
+		return this.asyncServer.listPrompts().collectList().block();
+	}
+
 	/**
 	 * Remove a prompt handler at runtime.
 	 * @param promptName The name of the prompt handler to remove
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
index 2852937ab..10f0e5a31 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java
@@ -89,6 +89,14 @@ public void addTool(McpServerFeatures.SyncToolSpecification toolHandler) {
 			.block();
 	}
 
+	/**
+	 * List all registered tools.
+	 * @return A list of all registered tools
+	 */
+	public List listTools() {
+		return this.asyncServer.listTools().collectList().block();
+	}
+
 	/**
 	 * Remove a tool handler.
 	 * @param toolName The name of the tool handler to remove
@@ -162,6 +170,14 @@ public void addPrompt(McpServerFeatures.SyncPromptSpecification promptSpecificat
 			.block();
 	}
 
+	/**
+	 * List all registered prompts.
+	 * @return A list of all registered prompts
+	 */
+	public List listPrompts() {
+		return this.asyncServer.listPrompts().collectList().block();
+	}
+
 	/**
 	 * Remove a prompt handler.
 	 * @param promptName The name of the prompt handler to remove
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
index 5e6f5990b..d6e549fdc 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpError.java
@@ -38,11 +38,12 @@ public JSONRPCError getJsonRpcError() {
 
 	@Override
 	public String toString() {
-		var message = super.toString();
+		var builder = new StringBuilder(super.toString());
 		if (jsonRpcError != null) {
-			return message + jsonRpcError.toString();
+			builder.append("\n");
+			builder.append(jsonRpcError.toString());
 		}
-		return message;
+		return builder.toString();
 	}
 
 	public static Builder builder(int errorCode) {
@@ -78,4 +79,38 @@ public McpError build() {
 
 	}
 
+	public static Throwable findRootCause(Throwable throwable) {
+		Assert.notNull(throwable, "throwable must not be null");
+		Throwable rootCause = throwable;
+		while (rootCause.getCause() != null && rootCause.getCause() != rootCause) {
+			rootCause = rootCause.getCause();
+		}
+		return rootCause;
+	}
+
+	public static String aggregateExceptionMessages(Throwable throwable) {
+		Assert.notNull(throwable, "throwable must not be null");
+
+		StringBuilder messages = new StringBuilder();
+		Throwable current = throwable;
+
+		while (current != null) {
+			if (messages.length() > 0) {
+				messages.append("\n  Caused by: ");
+			}
+
+			messages.append(current.getClass().getSimpleName());
+			if (current.getMessage() != null) {
+				messages.append(": ").append(current.getMessage());
+			}
+
+			if (current.getCause() == current) {
+				break;
+			}
+			current = current.getCause();
+		}
+
+		return messages.toString();
+	}
+
 }
\ No newline at end of file
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
index b9ff041a9..241f7d8b5 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpServerSession.java
@@ -224,9 +224,12 @@ public Mono handle(McpSchema.JSONRPCMessage message) {
 			else if (message instanceof McpSchema.JSONRPCRequest request) {
 				logger.debug("Received request: {}", request);
 				return handleIncomingRequest(request, transportContext).onErrorResume(error -> {
+					McpSchema.JSONRPCResponse.JSONRPCError jsonRpcError = (error instanceof McpError mcpError
+							&& mcpError.getJsonRpcError() != null) ? mcpError.getJsonRpcError()
+									: new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
+											error.getMessage(), McpError.aggregateExceptionMessages(error));
 					var errorResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null,
-							new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
-									error.getMessage(), null));
+							jsonRpcError);
 					// TODO: Should the error go to SSE or back as POST return?
 					return this.transport.sendMessage(errorResponse).then(Mono.empty());
 				}).flatMap(this.transport::sendMessage);
@@ -282,10 +285,15 @@ private Mono handleIncomingRequest(McpSchema.JSONRPCR
 			}
 			return resultMono
 				.map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), result, null))
-				.onErrorResume(error -> Mono.just(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
-						null, new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
-								error.getMessage(), null)))); // TODO: add error message
-																// through the data field
+				.onErrorResume(error -> {
+					McpSchema.JSONRPCResponse.JSONRPCError jsonRpcError = (error instanceof McpError mcpError
+							&& mcpError.getJsonRpcError() != null) ? mcpError.getJsonRpcError()
+									// TODO: add error message through the data field
+									: new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
+											error.getMessage(), McpError.aggregateExceptionMessages(error));
+					return Mono.just(
+							new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null, jsonRpcError));
+				});
 		});
 	}
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
index ec03dd424..95f8959f5 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpStreamableServerSession.java
@@ -179,9 +179,13 @@ public Mono responseStream(McpSchema.JSONRPCRequest jsonrpcRequest, McpStr
 				.map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(), result,
 						null))
 				.onErrorResume(e -> {
+					McpSchema.JSONRPCResponse.JSONRPCError jsonRpcError = (e instanceof McpError mcpError
+							&& mcpError.getJsonRpcError() != null) ? mcpError.getJsonRpcError()
+									: new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
+											e.getMessage(), McpError.aggregateExceptionMessages(e));
+
 					var errorResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, jsonrpcRequest.id(),
-							null, new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
-									e.getMessage(), null));
+							null, jsonRpcError);
 					return Mono.just(errorResponse);
 				})
 				.flatMap(transport::sendMessage)
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index f8f17cdfb..aa68203dd 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -145,13 +145,9 @@ void testAddDuplicateTool() {
 			.tool(duplicateTool, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
 
-		StepVerifier
-			.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
-					(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
-			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class)
-					.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
-			});
+		StepVerifier.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
+				(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
+			.verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 	}
@@ -172,10 +168,7 @@ void testAddDuplicateToolCall() {
 		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(duplicateTool)
 			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
-			.build())).verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class)
-					.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
-			});
+			.build())).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 	}
@@ -269,9 +262,7 @@ void testRemoveNonexistentTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		StepVerifier.create(mcpAsyncServer.removeTool("nonexistent-tool")).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class).hasMessage("Tool with name 'nonexistent-tool' not found");
-		});
+		StepVerifier.create(mcpAsyncServer.removeTool("nonexistent-tool")).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 	}
@@ -512,9 +503,6 @@ void testRemoveNonexistentResourceTemplate() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		// Removing a non-existent resource template should complete successfully (no
-		// error)
-		// as per the new implementation that just logs a warning
 		StepVerifier.create(mcpAsyncServer.removeResourceTemplate("nonexistent://template/{id}")).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -570,7 +558,8 @@ void testAddPromptWithNullSpecification() {
 
 		StepVerifier.create(mcpAsyncServer.addPrompt((McpServerFeatures.AsyncPromptSpecification) null))
 			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class).hasMessage("Prompt specification must not be null");
+				assertThat(error).isInstanceOf(IllegalArgumentException.class)
+					.hasMessage("Prompt specification must not be null");
 			});
 	}
 
@@ -585,7 +574,7 @@ void testAddPromptWithoutCapability() {
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))));
 
 		StepVerifier.create(serverWithoutPrompts.addPrompt(specification)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with prompt capabilities");
 		});
 	}
@@ -596,7 +585,7 @@ void testRemovePromptWithoutCapability() {
 		McpAsyncServer serverWithoutPrompts = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with prompt capabilities");
 		});
 	}
@@ -626,10 +615,7 @@ void testRemoveNonexistentPrompt() {
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
-		StepVerifier.create(mcpAsyncServer2.removePrompt("nonexistent-prompt")).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
-				.hasMessage("Prompt with name 'nonexistent-prompt' not found");
-		});
+		StepVerifier.create(mcpAsyncServer2.removePrompt("nonexistent-prompt")).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer2.closeGracefully().block(Duration.ofSeconds(10)))
 			.doesNotThrowAnyException();
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index 3fd0f2cfb..603324631 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -146,8 +146,9 @@ void testCreateMessageSuccess(String clientType) {
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		AtomicReference samplingResult = new AtomicReference<>();
 
@@ -224,8 +225,9 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 
 		// Server
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		AtomicReference samplingResult = new AtomicReference<>();
 
@@ -300,8 +302,9 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
@@ -393,8 +396,9 @@ void testCreateElicitationSuccess(String clientType) {
 					Map.of("message", request.message()));
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
@@ -448,8 +452,9 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		AtomicReference resultRef = new AtomicReference<>();
 
@@ -520,7 +525,7 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		CallToolResult callResponse = CallToolResult.builder().addContent(new TextContent("CALL RESPONSE")).build();
 
 		AtomicReference resultRef = new AtomicReference<>();
 
@@ -761,7 +766,9 @@ void testToolCallSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		var callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE; ctx=importantValue"))
+			.build();
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
@@ -832,8 +839,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 			assertThat(initResult).isNotNull();
 
 			// We expect the tool call to fail immediately with the exception raised by
-			// the offending tool
-			// instead of getting back a timeout.
+			// the offending tool instead of getting back a timeout.
 			assertThatExceptionOfType(McpError.class)
 				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
 				.withMessageContaining("Timeout on blocking read");
@@ -853,8 +859,9 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 		var transportContextIsEmpty = new AtomicBoolean(false);
 		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
 
-		var expectedCallResponse = new McpSchema.CallToolResult(
-				List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=value")), null);
+		var expectedCallResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE; ctx=value"))
+			.build();
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
@@ -872,8 +879,9 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 					e.printStackTrace();
 				}
 
-				return new McpSchema.CallToolResult(
-						List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=" + ctxValue)), null);
+				return McpSchema.CallToolResult.builder()
+					.addContent(new McpSchema.TextContent("CALL RESPONSE; ctx=" + ctxValue))
+					.build();
 			})
 			.build();
 
@@ -906,7 +914,10 @@ void testToolListChangeHandlingSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		var callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
+
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 619bb7aa4..976eb8c2c 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -154,10 +154,9 @@ void testAddDuplicateTool() {
 			.tool(duplicateTool, (exchange, args) -> new CallToolResult(List.of(), false))
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
+		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
 				(exchange, args) -> new CallToolResult(List.of(), false))))
-			.isInstanceOf(McpError.class)
-			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
+			.doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
@@ -175,11 +174,10 @@ void testAddDuplicateToolCall() {
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
+		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(duplicateTool)
 			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
-			.build())).isInstanceOf(McpError.class)
-			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
+			.build())).doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
@@ -272,8 +270,7 @@ void testRemoveNonexistentTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.removeTool("nonexistent-tool")).isInstanceOf(McpError.class)
-			.hasMessage("Tool with name 'nonexistent-tool' not found");
+		assertThatCode(() -> mcpSyncServer.removeTool("nonexistent-tool")).doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
@@ -496,9 +493,6 @@ void testRemoveNonexistentResourceTemplate() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		// Removing a non-existent resource template should complete successfully (no
-		// error)
-		// as per the new implementation that just logs a warning
 		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("nonexistent://template/{id}"))
 			.doesNotThrowAnyException();
 
@@ -549,7 +543,7 @@ void testAddPromptWithNullSpecification() {
 			.build();
 
 		assertThatThrownBy(() -> mcpSyncServer.addPrompt((McpServerFeatures.SyncPromptSpecification) null))
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Prompt specification must not be null");
 	}
 
@@ -562,7 +556,8 @@ void testAddPromptWithoutCapability() {
 				(exchange, req) -> new GetPromptResult("Test prompt description", List
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))));
 
-		assertThatThrownBy(() -> serverWithoutPrompts.addPrompt(specification)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutPrompts.addPrompt(specification))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with prompt capabilities");
 	}
 
@@ -570,7 +565,8 @@ void testAddPromptWithoutCapability() {
 	void testRemovePromptWithoutCapability() {
 		var serverWithoutPrompts = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with prompt capabilities");
 	}
 
@@ -597,8 +593,7 @@ void testRemoveNonexistentPrompt() {
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.removePrompt("nonexistent-prompt")).isInstanceOf(McpError.class)
-			.hasMessage("Prompt with name 'nonexistent-prompt' not found");
+		assertThatCode(() -> mcpSyncServer.removePrompt("nonexistent://template/{id}")).doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 1b34c43a7..37a1ef31d 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -150,8 +150,9 @@ void testCreateMessageSuccess(String clientType) {
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		AtomicReference samplingResult = new AtomicReference<>();
 
@@ -228,8 +229,9 @@ void testCreateMessageWithRequestTimeoutSuccess(String clientType) throws Interr
 
 		// Server
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		AtomicReference samplingResult = new AtomicReference<>();
 
@@ -304,8 +306,9 @@ void testCreateMessageWithRequestTimeoutFail(String clientType) throws Interrupt
 					CreateMessageResult.StopReason.STOP_SEQUENCE);
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
@@ -397,8 +400,9 @@ void testCreateElicitationSuccess(String clientType) {
 					Map.of("message", request.message()));
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		McpServerFeatures.AsyncToolSpecification tool = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
@@ -452,8 +456,9 @@ void testCreateElicitationWithRequestTimeoutSuccess(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		CallToolResult callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")),
-				null);
+		CallToolResult callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
 
 		AtomicReference resultRef = new AtomicReference<>();
 
@@ -524,7 +529,7 @@ void testCreateElicitationWithRequestTimeoutFail(String clientType) {
 			return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
 		};
 
-		CallToolResult callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		CallToolResult callResponse = CallToolResult.builder().addContent(new TextContent("CALL RESPONSE")).build();
 
 		AtomicReference resultRef = new AtomicReference<>();
 
@@ -765,7 +770,9 @@ void testToolCallSuccess(String clientType) {
 		var clientBuilder = clientBuilders.get(clientType);
 
 		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		var callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE; ctx=importantValue"))
+			.build();
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
@@ -836,8 +843,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 			assertThat(initResult).isNotNull();
 
 			// We expect the tool call to fail immediately with the exception raised by
-			// the offending tool
-			// instead of getting back a timeout.
+			// the offending tool instead of getting back a timeout.
 			assertThatExceptionOfType(McpError.class)
 				.isThrownBy(() -> mcpClient.callTool(new McpSchema.CallToolRequest("tool1", Map.of())))
 				.withMessageContaining("Timeout on blocking read");
@@ -857,8 +863,9 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 		var transportContextIsEmpty = new AtomicBoolean(false);
 		var responseBodyIsNullOrBlank = new AtomicBoolean(false);
 
-		var expectedCallResponse = new McpSchema.CallToolResult(
-				List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=value")), null);
+		var expectedCallResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE; ctx=value"))
+			.build();
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
@@ -876,8 +883,9 @@ void testToolCallSuccessWithTranportContextExtraction(String clientType) {
 					e.printStackTrace();
 				}
 
-				return new McpSchema.CallToolResult(
-						List.of(new McpSchema.TextContent("CALL RESPONSE; ctx=" + ctxValue)), null);
+				return McpSchema.CallToolResult.builder()
+					.addContent(new McpSchema.TextContent("CALL RESPONSE; ctx=" + ctxValue))
+					.build();
 			})
 			.build();
 
@@ -910,7 +918,10 @@ void testToolListChangeHandlingSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
-		var callResponse = new McpSchema.CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		var callResponse = McpSchema.CallToolResult.builder()
+			.addContent(new McpSchema.TextContent("CALL RESPONSE"))
+			.build();
+
 		McpServerFeatures.SyncToolSpecification tool1 = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(Tool.builder().name("tool1").description("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build())
 			.callHandler((exchange, request) -> {
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index 4c4e49dc5..c24bcd622 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -149,13 +149,9 @@ void testAddDuplicateTool() {
 			.tool(duplicateTool, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
 			.build();
 
-		StepVerifier
-			.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
-					(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
-			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class)
-					.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
-			});
+		StepVerifier.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
+				(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
+			.verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 	}
@@ -176,10 +172,7 @@ void testAddDuplicateToolCall() {
 		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(duplicateTool)
 			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
-			.build())).verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class)
-					.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
-			});
+			.build())).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 	}
@@ -273,9 +266,7 @@ void testRemoveNonexistentTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		StepVerifier.create(mcpAsyncServer.removeTool("nonexistent-tool")).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class).hasMessage("Tool with name 'nonexistent-tool' not found");
-		});
+		StepVerifier.create(mcpAsyncServer.removeTool("nonexistent-tool")).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
 	}
@@ -516,9 +507,6 @@ void testRemoveNonexistentResourceTemplate() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		// Removing a non-existent resource template should complete successfully (no
-		// error)
-		// as per the new implementation that just logs a warning
 		StepVerifier.create(mcpAsyncServer.removeResourceTemplate("nonexistent://template/{id}")).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -574,7 +562,8 @@ void testAddPromptWithNullSpecification() {
 
 		StepVerifier.create(mcpAsyncServer.addPrompt((McpServerFeatures.AsyncPromptSpecification) null))
 			.verifyErrorSatisfies(error -> {
-				assertThat(error).isInstanceOf(McpError.class).hasMessage("Prompt specification must not be null");
+				assertThat(error).isInstanceOf(IllegalArgumentException.class)
+					.hasMessage("Prompt specification must not be null");
 			});
 	}
 
@@ -589,7 +578,7 @@ void testAddPromptWithoutCapability() {
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content"))))));
 
 		StepVerifier.create(serverWithoutPrompts.addPrompt(specification)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with prompt capabilities");
 		});
 	}
@@ -600,7 +589,7 @@ void testRemovePromptWithoutCapability() {
 		McpAsyncServer serverWithoutPrompts = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		StepVerifier.create(serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
+			assertThat(error).isInstanceOf(IllegalStateException.class)
 				.hasMessage("Server must be configured with prompt capabilities");
 		});
 	}
@@ -630,10 +619,7 @@ void testRemoveNonexistentPrompt() {
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
-		StepVerifier.create(mcpAsyncServer2.removePrompt("nonexistent-prompt")).verifyErrorSatisfies(error -> {
-			assertThat(error).isInstanceOf(McpError.class)
-				.hasMessage("Prompt with name 'nonexistent-prompt' not found");
-		});
+		StepVerifier.create(mcpAsyncServer2.removePrompt("nonexistent-prompt")).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer2.closeGracefully().block(Duration.ofSeconds(10)))
 			.doesNotThrowAnyException();
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index ff37abd74..591f750cb 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -153,10 +153,9 @@ void testAddDuplicateTool() {
 			.tool(duplicateTool, (exchange, args) -> new CallToolResult(List.of(), false))
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
+		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
 				(exchange, args) -> new CallToolResult(List.of(), false))))
-			.isInstanceOf(McpError.class)
-			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
+			.doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
@@ -174,11 +173,10 @@ void testAddDuplicateToolCall() {
 			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
+		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(duplicateTool)
 			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
-			.build())).isInstanceOf(McpError.class)
-			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
+			.build())).doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
@@ -271,8 +269,7 @@ void testRemoveNonexistentTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.removeTool("nonexistent-tool")).isInstanceOf(McpError.class)
-			.hasMessage("Tool with name 'nonexistent-tool' not found");
+		assertThatCode(() -> mcpSyncServer.removeTool("nonexistent-tool")).doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}
@@ -495,9 +492,6 @@ void testRemoveNonexistentResourceTemplate() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		// Removing a non-existent resource template should complete successfully (no
-		// error)
-		// as per the new implementation that just logs a warning
 		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("nonexistent://template/{id}"))
 			.doesNotThrowAnyException();
 
@@ -548,7 +542,7 @@ void testAddPromptWithNullSpecification() {
 			.build();
 
 		assertThatThrownBy(() -> mcpSyncServer.addPrompt((McpServerFeatures.SyncPromptSpecification) null))
-			.isInstanceOf(McpError.class)
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Prompt specification must not be null");
 	}
 
@@ -561,7 +555,8 @@ void testAddPromptWithoutCapability() {
 				(exchange, req) -> new GetPromptResult("Test prompt description", List
 					.of(new PromptMessage(McpSchema.Role.ASSISTANT, new McpSchema.TextContent("Test content")))));
 
-		assertThatThrownBy(() -> serverWithoutPrompts.addPrompt(specification)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutPrompts.addPrompt(specification))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with prompt capabilities");
 	}
 
@@ -569,7 +564,8 @@ void testAddPromptWithoutCapability() {
 	void testRemovePromptWithoutCapability() {
 		var serverWithoutPrompts = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME)).isInstanceOf(McpError.class)
+		assertThatThrownBy(() -> serverWithoutPrompts.removePrompt(TEST_PROMPT_NAME))
+			.isInstanceOf(IllegalStateException.class)
 			.hasMessage("Server must be configured with prompt capabilities");
 	}
 
@@ -596,8 +592,7 @@ void testRemoveNonexistentPrompt() {
 			.capabilities(ServerCapabilities.builder().prompts(true).build())
 			.build();
 
-		assertThatThrownBy(() -> mcpSyncServer.removePrompt("nonexistent-prompt")).isInstanceOf(McpError.class)
-			.hasMessage("Prompt with name 'nonexistent-prompt' not found");
+		assertThatCode(() -> mcpSyncServer.removePrompt("nonexistent://template/{id}")).doesNotThrowAnyException();
 
 		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
 	}

From 12292ab5984240ef8672e72dad2dbbd69f0aec05 Mon Sep 17 00:00:00 2001
From: Sergio del Amo 
Date: Tue, 30 Sep 2025 15:59:17 +0200
Subject: [PATCH 084/125] =?UTF-8?q?fix:=20when=20using=20JsonTypeInfo.DEDU?=
 =?UTF-8?q?CTION=20don=E2=80=99t=20add=20include=20(#587)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From the JSonTypeInfo Javadocs:

> If deduction is being used annotation properties visible, property and include are ignored.

This is causing issues with serialization downstream.
---
 .../src/main/java/io/modelcontextprotocol/spec/McpSchema.java   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 792aa54fa..8186bb199 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -1064,7 +1064,7 @@ public UnsubscribeRequest(String uri) {
 	/**
 	 * The contents of a specific resource or sub-resource.
 	 */
-	@JsonTypeInfo(use = JsonTypeInfo.Id.DEDUCTION, include = As.PROPERTY)
+	@JsonTypeInfo(use = JsonTypeInfo.Id.DEDUCTION)
 	@JsonSubTypes({ @JsonSubTypes.Type(value = TextResourceContents.class, name = "text"),
 			@JsonSubTypes.Type(value = BlobResourceContents.class, name = "blob") })
 	public sealed interface ResourceContents extends Meta permits TextResourceContents, BlobResourceContents {

From 080098e48cc206f71bb15cac35f5d8ec58926855 Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Wed, 1 Oct 2025 11:19:25 +0200
Subject: [PATCH 085/125] Client: handle server responses with Content-Length:
 0

- When the client sends `notification/initalized`, servers must respond
  with HTTP 202 and an empty body. We checked for the absence of a
  Content-Type header to verify whether the body was empty.
- However, some servers will send an empty body with a Content-Type
  header, and that header may have an unsupported, default type such as
  `text/html` or `text/plain`.
- Now we we also use the Content-Length header to check for an empty
  body. This header is optional in HTTP/2, so we do not make it our
  primary mechanism for detecting empty bodies.
- As part of this PR, we also move hard-coded HTTP header names to the
  HttpHeaders interface. While they are not defined by the MCP spec,
  they are used by it and are core to implementing the protocol.
  Therefore, they have their place in a core interface.
- Fixes #582

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../HttpClientSseClientTransport.java         | 11 ++++----
 .../HttpClientStreamableHttpTransport.java    | 24 ++++++++++-------
 .../spec/HttpHeaders.java                     | 27 +++++++++++++++++++
 .../WebClientStreamableHttpTransport.java     |  3 ++-
 4 files changed, 48 insertions(+), 17 deletions(-)

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 661a41170..ae093316f 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
@@ -18,14 +18,13 @@
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
-
-import io.modelcontextprotocol.json.McpJsonMapper;
-import io.modelcontextprotocol.json.TypeRef;
-
+import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
-import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
+import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.JSONRPCMessage;
@@ -469,7 +468,7 @@ private Mono> sendHttpPost(final String endpoint, final Str
 		return Mono.deferContextual(ctx -> {
 			var builder = this.requestBuilder.copy()
 				.uri(requestUri)
-				.header("Content-Type", "application/json")
+				.header(HttpHeaders.CONTENT_TYPE, "application/json")
 				.header(MCP_PROTOCOL_VERSION_HEADER_NAME, MCP_PROTOCOL_VERSION)
 				.POST(HttpRequest.BodyPublishers.ofString(body));
 			var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
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 fb8813542..854b3f297 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
@@ -246,7 +246,7 @@ private Mono reconnect(McpTransportStream stream) {
 				}
 
 				var builder = requestBuilder.uri(uri)
-					.header("Accept", TEXT_EVENT_STREAM)
+					.header(HttpHeaders.ACCEPT, TEXT_EVENT_STREAM)
 					.header("Cache-Control", "no-cache")
 					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.GET();
@@ -371,7 +371,7 @@ private BodyHandler toSendMessageBodySubscriber(FluxSink si
 
 		BodyHandler responseBodyHandler = responseInfo -> {
 
-			String contentType = responseInfo.headers().firstValue("Content-Type").orElse("").toLowerCase();
+			String contentType = responseInfo.headers().firstValue(HttpHeaders.CONTENT_TYPE).orElse("").toLowerCase();
 
 			if (contentType.contains(TEXT_EVENT_STREAM)) {
 				// For SSE streams, use line subscriber that returns Void
@@ -420,9 +420,9 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 				}
 
 				var builder = requestBuilder.uri(uri)
-					.header("Accept", APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
-					.header("Content-Type", APPLICATION_JSON)
-					.header("Cache-Control", "no-cache")
+					.header(HttpHeaders.ACCEPT, APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
+					.header(HttpHeaders.CONTENT_TYPE, APPLICATION_JSON)
+					.header(HttpHeaders.CACHE_CONTROL, "no-cache")
 					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
 					.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
 				var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
@@ -459,15 +459,19 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 
 					String contentType = responseEvent.responseInfo()
 						.headers()
-						.firstValue("Content-Type")
+						.firstValue(HttpHeaders.CONTENT_TYPE)
 						.orElse("")
 						.toLowerCase();
 
-					if (contentType.isBlank()) {
-						logger.debug("No content type returned for POST in session {}", sessionRepresentation);
+					String contentLength = responseEvent.responseInfo()
+						.headers()
+						.firstValue(HttpHeaders.CONTENT_LENGTH)
+						.orElse(null);
+
+					if (contentType.isBlank() || "0".equals(contentLength)) {
+						logger.debug("No body returned for POST in session {}", sessionRepresentation);
 						// No content type means no response body, so we can just
-						// return
-						// an empty stream
+						// return an empty stream
 						deliveredSink.success();
 						return Flux.empty();
 					}
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
index 370b47070..6afc2c119 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/HttpHeaders.java
@@ -26,4 +26,31 @@ public interface HttpHeaders {
 	 */
 	String PROTOCOL_VERSION = "MCP-Protocol-Version";
 
+	/**
+	 * The HTTP Content-Length header.
+	 * @see RFC9110
+	 */
+	String CONTENT_LENGTH = "Content-Length";
+
+	/**
+	 * The HTTP Content-Type header.
+	 * @see RFC9110
+	 */
+	String CONTENT_TYPE = "Content-Type";
+
+	/**
+	 * The HTTP Accept header.
+	 * @see RFC9110
+	 */
+	String ACCEPT = "Accept";
+
+	/**
+	 * The HTTP Cache-Control header.
+	 * @see RFC9111
+	 */
+	String CACHE_CONTROL = "Cache-Control";
+
 }
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 24f9e1d0b..860b1958e 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -293,9 +293,10 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 					// 200 OK for notifications
 					if (response.statusCode().is2xxSuccessful()) {
 						Optional contentType = response.headers().contentType();
+						long contentLength = response.headers().contentLength().orElse(-1);
 						// Existing SDKs consume notifications with no response body nor
 						// content type
-						if (contentType.isEmpty()) {
+						if (contentType.isEmpty() || contentLength == 0) {
 							logger.trace("Message was successfully sent via POST for session {}",
 									sessionRepresentation);
 							// signal the caller that the message was successfully

From 3f7578b3cecacb2d76094f5fa8d0c514ee921ed9 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Wed, 1 Oct 2025 23:14:29 +0200
Subject: [PATCH 086/125] fix: Handle non-compliant notification responses
 (#589)

Ensure warnings are logged for all non-compliant responses to JSON-RPC
notifications, including empty responses. Empty responses now display
as "[empty]" in log messages for better clarity.

Resolves #586

Signed-off-by: Christian Tzolov 
---
 .../client/transport/HttpClientStreamableHttpTransport.java  | 5 +++--
 .../client/transport/WebClientStreamableHttpTransport.java   | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

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 854b3f297..f4505c898 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
@@ -507,8 +507,9 @@ else if (contentType.contains(TEXT_EVENT_STREAM)) {
 					else if (contentType.contains(APPLICATION_JSON)) {
 						deliveredSink.success();
 						String data = ((ResponseSubscribers.AggregateResponseEvent) responseEvent).data();
-						if (sentMessage instanceof McpSchema.JSONRPCNotification && Utils.hasText(data)) {
-							logger.warn("Notification: {} received non-compliant response: {}", sentMessage, data);
+						if (sentMessage instanceof McpSchema.JSONRPCNotification) {
+							logger.warn("Notification: {} received non-compliant response: {}", sentMessage,
+									Utils.hasText(data) ? data : "[empty]");
 							return Mono.empty();
 						}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 860b1958e..f6ce9b4d3 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -423,8 +423,9 @@ private Flux directResponseFlux(McpSchema.JSONRPCMessa
 			ClientResponse response) {
 		return response.bodyToMono(String.class).>handle((responseMessage, s) -> {
 			try {
-				if (sentMessage instanceof McpSchema.JSONRPCNotification && Utils.hasText(responseMessage)) {
-					logger.warn("Notification: {} received non-compliant response: {}", sentMessage, responseMessage);
+				if (sentMessage instanceof McpSchema.JSONRPCNotification) {
+					logger.warn("Notification: {} received non-compliant response: {}", sentMessage,
+							Utils.hasText(responseMessage) ? responseMessage : "[empty]");
 					s.complete();
 				}
 				else {

From 8e11fa82ae0291d9b29566f5ab1299ddcb1ac639 Mon Sep 17 00:00:00 2001
From: Anurag Pant 
Date: Sun, 21 Sep 2025 20:12:32 -0700
Subject: [PATCH 087/125] feat(client): add client tool output schema
 validation and caching (#302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add JSON schema validation for tool call results against output schemas
- Implement automatic tool output schema caching during initialization
- Add `enableCallToolSchemaCaching` configuration option to enable/disable
  schema caching
- Add `JsonSchemaValidator` integration to McpClient builder APIs
- Introduce post-initialization hook mechanism for performing operations
  after successful client initialization
- Cache tool output schemas during `listTools` operations when caching
  is enabled
- Validate tool results against cached schemas in `callTool` operations
- Return error CallToolResult when validation fails
- Add test coverage
- Convert validateToolResult from Mono to synchronous method
- Throw IllegalArgumentException on validation errors

Signed-off-by: Christian Tzolov 

Co-authored-by: Anurag Pant 
Co-authored-by: Christian Tzolov 
Co-authored-by: Daniel Garnier-Moiroux 
Co-authored-by: Dariusz Jędrzejczyk 
---
 .../client/LifecycleInitializer.java          |  54 ++--
 .../client/McpAsyncClient.java                | 163 +++++++---
 .../client/McpClient.java                     |  74 ++++-
 .../client/McpClientFeatures.java             |  25 +-
 .../modelcontextprotocol/spec/McpSchema.java  |   1 -
 ...pClientStreamableHttpAsyncClientTests.java |   5 +-
 ...nitializerPostInitializationHookTests.java | 280 ++++++++++++++++++
 .../client/LifecycleInitializerTests.java     |  70 ++---
 .../client/McpAsyncClientTests.java           | 154 ++++++++++
 .../client/McpClientProtocolVersionTests.java |  13 +-
 10 files changed, 708 insertions(+), 131 deletions(-)
 create mode 100644 mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerPostInitializationHookTests.java

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
index 2fc669c15..f56c79a6d 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
@@ -11,14 +11,13 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.util.Assert;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Mono;
 import reactor.core.publisher.Sinks;
 import reactor.util.context.ContextView;
@@ -99,21 +98,30 @@ class LifecycleInitializer {
 	 */
 	private final Duration initializationTimeout;
 
+	/**
+	 * Post-initialization hook to perform additional operations after every successful
+	 * initialization.
+	 */
+	private final Function> postInitializationHook;
+
 	public LifecycleInitializer(McpSchema.ClientCapabilities clientCapabilities, McpSchema.Implementation clientInfo,
 			List protocolVersions, Duration initializationTimeout,
-			Function sessionSupplier) {
+			Function sessionSupplier,
+			Function> postInitializationHook) {
 
 		Assert.notNull(sessionSupplier, "Session supplier must not be null");
 		Assert.notNull(clientCapabilities, "Client capabilities must not be null");
 		Assert.notNull(clientInfo, "Client info must not be null");
 		Assert.notEmpty(protocolVersions, "Protocol versions must not be empty");
 		Assert.notNull(initializationTimeout, "Initialization timeout must not be null");
+		Assert.notNull(postInitializationHook, "Post-initialization hook must not be null");
 
 		this.sessionSupplier = sessionSupplier;
 		this.clientCapabilities = clientCapabilities;
 		this.clientInfo = clientInfo;
 		this.protocolVersions = Collections.unmodifiableList(new ArrayList<>(protocolVersions));
 		this.initializationTimeout = initializationTimeout;
+		this.postInitializationHook = postInitializationHook;
 	}
 
 	/**
@@ -148,10 +156,6 @@ interface Initialization {
 
 	}
 
-	/**
-	 * Default implementation of the {@link Initialization} interface that manages the MCP
-	 * client initialization process.
-	 */
 	private static class DefaultInitialization implements Initialization {
 
 		/**
@@ -199,29 +203,20 @@ private void setMcpClientSession(McpClientSession mcpClientSession) {
 			this.mcpClientSession.set(mcpClientSession);
 		}
 
-		/**
-		 * Returns a Mono that completes when the MCP client initialization is complete.
-		 * This allows subscribers to wait for the initialization to finish before
-		 * proceeding with further operations.
-		 * @return A Mono that emits the result of the MCP initialization process
-		 */
 		private Mono await() {
 			return this.initSink.asMono();
 		}
 
-		/**
-		 * Completes the initialization process with the given result. It caches the
-		 * result and emits it to all subscribers waiting for the initialization to
-		 * complete.
-		 * @param initializeResult The result of the MCP initialization process
-		 */
 		private void complete(McpSchema.InitializeResult initializeResult) {
-			// first ensure the result is cached
-			this.result.set(initializeResult);
 			// inform all the subscribers waiting for the initialization
 			this.initSink.emitValue(initializeResult, Sinks.EmitFailureHandler.FAIL_FAST);
 		}
 
+		private void cacheResult(McpSchema.InitializeResult initializeResult) {
+			// first ensure the result is cached
+			this.result.set(initializeResult);
+		}
+
 		private void error(Throwable t) {
 			this.initSink.emitError(t, Sinks.EmitFailureHandler.FAIL_FAST);
 		}
@@ -263,7 +258,7 @@ public void handleException(Throwable t) {
 			}
 			// Providing an empty operation since we are only interested in triggering
 			// the implicit initialization step.
-			withIntitialization("re-initializing", result -> Mono.empty()).subscribe();
+			this.withInitialization("re-initializing", result -> Mono.empty()).subscribe();
 		}
 	}
 
@@ -275,7 +270,7 @@ public void handleException(Throwable t) {
 	 * @param operation The operation to execute when the client is initialized
 	 * @return A Mono that completes with the result of the operation
 	 */
-	public  Mono withIntitialization(String actionName, Function> operation) {
+	public  Mono withInitialization(String actionName, Function> operation) {
 		return Mono.deferContextual(ctx -> {
 			DefaultInitialization newInit = new DefaultInitialization();
 			DefaultInitialization previous = this.initializationRef.compareAndExchange(null, newInit);
@@ -283,8 +278,8 @@ public  Mono withIntitialization(String actionName, Function initializationJob = needsToInitialize ? doInitialize(newInit, ctx)
-					: previous.await();
+			Mono initializationJob = needsToInitialize
+					? this.doInitialize(newInit, this.postInitializationHook, ctx) : previous.await();
 
 			return initializationJob.map(initializeResult -> this.initializationRef.get())
 				.timeout(this.initializationTimeout)
@@ -296,7 +291,9 @@ public  Mono withIntitialization(String actionName, Function doInitialize(DefaultInitialization initialization, ContextView ctx) {
+	private Mono doInitialize(DefaultInitialization initialization,
+			Function> postInitOperation, ContextView ctx) {
+
 		initialization.setMcpClientSession(this.sessionSupplier.apply(ctx));
 
 		McpClientSession mcpClientSession = initialization.mcpSession();
@@ -323,6 +320,9 @@ private Mono doInitialize(DefaultInitialization init
 
 			return mcpClientSession.sendNotification(McpSchema.METHOD_NOTIFICATION_INITIALIZED, null)
 				.thenReturn(initializeResult);
+		}).flatMap(initializeResult -> {
+			initialization.cacheResult(initializeResult);
+			return postInitOperation.apply(initialization).thenReturn(initializeResult);
 		}).doOnNext(initialization::complete).onErrorResume(ex -> {
 			initialization.error(ex);
 			return Mono.error(ex);
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 8d5bc34a6..53a05aec3 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -15,12 +15,12 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Function;
 
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
+import io.modelcontextprotocol.client.LifecycleInitializer.Initialization;
 import io.modelcontextprotocol.json.TypeRef;
-
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpClientSession;
+import io.modelcontextprotocol.spec.McpClientSession.NotificationHandler;
+import io.modelcontextprotocol.spec.McpClientSession.RequestHandler;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
@@ -35,10 +35,10 @@
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 import io.modelcontextprotocol.spec.McpSchema.PaginatedRequest;
 import io.modelcontextprotocol.spec.McpSchema.Root;
-import io.modelcontextprotocol.spec.McpClientSession.NotificationHandler;
-import io.modelcontextprotocol.spec.McpClientSession.RequestHandler;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
@@ -75,6 +75,7 @@
  * @author Dariusz Jędrzejczyk
  * @author Christian Tzolov
  * @author Jihoon Kim
+ * @author Anurag Pant
  * @see McpClient
  * @see McpSchema
  * @see McpClientSession
@@ -152,16 +153,33 @@ public class McpAsyncClient {
 	 */
 	private final LifecycleInitializer initializer;
 
+	/**
+	 * JSON schema validator to use for validating tool responses against output schemas.
+	 */
+	private final JsonSchemaValidator jsonSchemaValidator;
+
+	/**
+	 * Cached tool output schemas.
+	 */
+	private final ConcurrentHashMap> toolsOutputSchemaCache;
+
+	/**
+	 * Whether to enable automatic schema caching during callTool operations.
+	 */
+	private final boolean enableCallToolSchemaCaching;
+
 	/**
 	 * Create a new McpAsyncClient with the given transport and session request-response
 	 * timeout.
 	 * @param transport the transport to use.
 	 * @param requestTimeout the session request-response timeout.
 	 * @param initializationTimeout the max timeout to await for the client-server
-	 * @param features the MCP Client supported features.
+	 * @param jsonSchemaValidator the JSON schema validator to use for validating tool
+	 * @param features the MCP Client supported features. responses against output
+	 * schemas.
 	 */
 	McpAsyncClient(McpClientTransport transport, Duration requestTimeout, Duration initializationTimeout,
-			McpClientFeatures.Async features) {
+			JsonSchemaValidator jsonSchemaValidator, McpClientFeatures.Async features) {
 
 		Assert.notNull(transport, "Transport must not be null");
 		Assert.notNull(requestTimeout, "Request timeout must not be null");
@@ -171,6 +189,9 @@ public class McpAsyncClient {
 		this.clientCapabilities = features.clientCapabilities();
 		this.transport = transport;
 		this.roots = new ConcurrentHashMap<>(features.roots());
+		this.jsonSchemaValidator = jsonSchemaValidator;
+		this.toolsOutputSchemaCache = new ConcurrentHashMap<>();
+		this.enableCallToolSchemaCaching = features.enableCallToolSchemaCaching();
 
 		// Request Handlers
 		Map> requestHandlers = new HashMap<>();
@@ -273,9 +294,30 @@ public class McpAsyncClient {
 		notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_PROGRESS,
 				asyncProgressNotificationHandler(progressConsumersFinal));
 
+		Function> postInitializationHook = init -> {
+
+			if (init.initializeResult().capabilities().tools() == null || !enableCallToolSchemaCaching) {
+				return Mono.empty();
+			}
+
+			return this.listToolsInternal(init, McpSchema.FIRST_PAGE).doOnNext(listToolsResult -> {
+				listToolsResult.tools()
+					.forEach(tool -> logger.debug("Tool {} schema: {}", tool.name(), tool.outputSchema()));
+				if (enableCallToolSchemaCaching && listToolsResult.tools() != null) {
+					// Cache tools output schema
+					listToolsResult.tools()
+						.stream()
+						.filter(tool -> tool.outputSchema() != null)
+						.forEach(tool -> this.toolsOutputSchemaCache.put(tool.name(), tool.outputSchema()));
+				}
+			}).then();
+		};
+
 		this.initializer = new LifecycleInitializer(clientCapabilities, clientInfo, transport.protocolVersions(),
 				initializationTimeout, ctx -> new McpClientSession(requestTimeout, transport, requestHandlers,
-						notificationHandlers, con -> con.contextWrite(ctx)));
+						notificationHandlers, con -> con.contextWrite(ctx)),
+				postInitializationHook);
+
 		this.transport.setExceptionHandler(this.initializer::handleException);
 	}
 
@@ -387,7 +429,7 @@ public Mono closeGracefully() {
 	 * 

 	 */
 	public Mono initialize() {
-		return this.initializer.withIntitialization("by explicit API call", init -> Mono.just(init.initializeResult()));
+		return this.initializer.withInitialization("by explicit API call", init -> Mono.just(init.initializeResult()));
 	}
 
 	// --------------------------
@@ -399,7 +441,7 @@ public Mono initialize() {
 	 * @return A Mono that completes with the server's ping response
 	 */
 	public Mono ping() {
-		return this.initializer.withIntitialization("pinging the server",
+		return this.initializer.withInitialization("pinging the server",
 				init -> init.mcpSession().sendRequest(McpSchema.METHOD_PING, null, OBJECT_TYPE_REF));
 	}
 
@@ -480,7 +522,7 @@ public Mono removeRoot(String rootUri) {
 	 * @return A Mono that completes when the notification is sent.
 	 */
 	public Mono rootsListChangedNotification() {
-		return this.initializer.withIntitialization("sending roots list changed notification",
+		return this.initializer.withInitialization("sending roots list changed notification",
 				init -> init.mcpSession().sendNotification(McpSchema.METHOD_NOTIFICATION_ROOTS_LIST_CHANGED));
 	}
 
@@ -539,15 +581,45 @@ private RequestHandler elicitationCreateHandler() {
 	 * @see #listTools()
 	 */
 	public Mono callTool(McpSchema.CallToolRequest callToolRequest) {
-		return this.initializer.withIntitialization("calling tools", init -> {
+		return this.initializer.withInitialization("calling tool", init -> {
 			if (init.initializeResult().capabilities().tools() == null) {
 				return Mono.error(new IllegalStateException("Server does not provide tools capability"));
 			}
+
 			return init.mcpSession()
-				.sendRequest(McpSchema.METHOD_TOOLS_CALL, callToolRequest, CALL_TOOL_RESULT_TYPE_REF);
+				.sendRequest(McpSchema.METHOD_TOOLS_CALL, callToolRequest, CALL_TOOL_RESULT_TYPE_REF)
+				.flatMap(result -> Mono.just(validateToolResult(callToolRequest.name(), result)));
 		});
 	}
 
+	private McpSchema.CallToolResult validateToolResult(String toolName, McpSchema.CallToolResult result) {
+
+		if (!this.enableCallToolSchemaCaching || result == null || result.isError() == Boolean.TRUE) {
+			// if tool schema caching is disabled or tool call resulted in an error - skip
+			// validation and return the result as it is
+			return result;
+		}
+
+		Map optOutputSchema = this.toolsOutputSchemaCache.get(toolName);
+
+		if (optOutputSchema == null) {
+			logger.warn(
+					"Calling a tool with no outputSchema is not expected to return result with structured content, but got: {}",
+					result.structuredContent());
+			return result;
+		}
+
+		// Validate the tool output against the cached output schema
+		var validation = this.jsonSchemaValidator.validate(optOutputSchema, result.structuredContent());
+
+		if (!validation.valid()) {
+			logger.warn("Tool call result validation failed: {}", validation.errorMessage());
+			throw new IllegalArgumentException("Tool call result validation failed: " + validation.errorMessage());
+		}
+
+		return result;
+	}
+
 	/**
 	 * Retrieves the list of all tools provided by the server.
 	 * @return A Mono that emits the list of all tools result
@@ -568,14 +640,26 @@ public Mono listTools() {
 	 * @return A Mono that emits the list of tools result
 	 */
 	public Mono listTools(String cursor) {
-		return this.initializer.withIntitialization("listing tools", init -> {
-			if (init.initializeResult().capabilities().tools() == null) {
-				return Mono.error(new IllegalStateException("Server does not provide tools capability"));
-			}
-			return init.mcpSession()
-				.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
-						LIST_TOOLS_RESULT_TYPE_REF);
-		});
+		return this.initializer.withInitialization("listing tools", init -> this.listToolsInternal(init, cursor));
+	}
+
+	private Mono listToolsInternal(Initialization init, String cursor) {
+
+		if (init.initializeResult().capabilities().tools() == null) {
+			return Mono.error(new IllegalStateException("Server does not provide tools capability"));
+		}
+		return init.mcpSession()
+			.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
+					LIST_TOOLS_RESULT_TYPE_REF)
+			.doOnNext(result -> {
+				if (this.enableCallToolSchemaCaching && result.tools() != null) {
+					// Cache tools output schema
+					result.tools()
+						.stream()
+						.filter(tool -> tool.outputSchema() != null)
+						.forEach(tool -> this.toolsOutputSchemaCache.put(tool.name(), tool.outputSchema()));
+				}
+			});
 	}
 
 	private NotificationHandler asyncToolsChangeNotificationHandler(
@@ -632,7 +716,7 @@ public Mono listResources() {
 	 * @see #readResource(McpSchema.Resource)
 	 */
 	public Mono listResources(String cursor) {
-		return this.initializer.withIntitialization("listing resources", init -> {
+		return this.initializer.withInitialization("listing resources", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
 				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
@@ -664,7 +748,7 @@ public Mono readResource(McpSchema.Resource resour
 	 * @see McpSchema.ReadResourceResult
 	 */
 	public Mono readResource(McpSchema.ReadResourceRequest readResourceRequest) {
-		return this.initializer.withIntitialization("reading resources", init -> {
+		return this.initializer.withInitialization("reading resources", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
 				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
@@ -702,7 +786,7 @@ public Mono listResourceTemplates() {
 	 * @see McpSchema.ListResourceTemplatesResult
 	 */
 	public Mono listResourceTemplates(String cursor) {
-		return this.initializer.withIntitialization("listing resource templates", init -> {
+		return this.initializer.withInitialization("listing resource templates", init -> {
 			if (init.initializeResult().capabilities().resources() == null) {
 				return Mono.error(new IllegalStateException("Server does not provide the resources capability"));
 			}
@@ -722,7 +806,7 @@ public Mono listResourceTemplates(String
 	 * @see #unsubscribeResource(McpSchema.UnsubscribeRequest)
 	 */
 	public Mono subscribeResource(McpSchema.SubscribeRequest subscribeRequest) {
-		return this.initializer.withIntitialization("subscribing to resources", init -> init.mcpSession()
+		return this.initializer.withInitialization("subscribing to resources", init -> init.mcpSession()
 			.sendRequest(McpSchema.METHOD_RESOURCES_SUBSCRIBE, subscribeRequest, VOID_TYPE_REFERENCE));
 	}
 
@@ -736,7 +820,7 @@ public Mono subscribeResource(McpSchema.SubscribeRequest subscribeRequest)
 	 * @see #subscribeResource(McpSchema.SubscribeRequest)
 	 */
 	public Mono unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest) {
-		return this.initializer.withIntitialization("unsubscribing from resources", init -> init.mcpSession()
+		return this.initializer.withInitialization("unsubscribing from resources", init -> init.mcpSession()
 			.sendRequest(McpSchema.METHOD_RESOURCES_UNSUBSCRIBE, unsubscribeRequest, VOID_TYPE_REFERENCE));
 	}
 
@@ -802,7 +886,7 @@ public Mono listPrompts() {
 	 * @see #getPrompt(GetPromptRequest)
 	 */
 	public Mono listPrompts(String cursor) {
-		return this.initializer.withIntitialization("listing prompts", init -> init.mcpSession()
+		return this.initializer.withInitialization("listing prompts", init -> init.mcpSession()
 			.sendRequest(McpSchema.METHOD_PROMPT_LIST, new PaginatedRequest(cursor), LIST_PROMPTS_RESULT_TYPE_REF));
 	}
 
@@ -816,7 +900,7 @@ public Mono listPrompts(String cursor) {
 	 * @see #listPrompts()
 	 */
 	public Mono getPrompt(GetPromptRequest getPromptRequest) {
-		return this.initializer.withIntitialization("getting prompts", init -> init.mcpSession()
+		return this.initializer.withInitialization("getting prompts", init -> init.mcpSession()
 			.sendRequest(McpSchema.METHOD_PROMPT_GET, getPromptRequest, GET_PROMPT_RESULT_TYPE_REF));
 	}
 
@@ -834,14 +918,6 @@ private NotificationHandler asyncPromptsChangeNotificationHandler(
 	// --------------------------
 	// Logging
 	// --------------------------
-	/**
-	 * Create a notification handler for logging notifications from the server. This
-	 * handler automatically distributes logging messages to all registered consumers.
-	 * @param loggingConsumers List of consumers that will be notified when a logging
-	 * message is received. Each consumer receives the logging message notification.
-	 * @return A NotificationHandler that processes log notifications by distributing the
-	 * message to all registered consumers
-	 */
 	private NotificationHandler asyncLoggingNotificationHandler(
 			List>> loggingConsumers) {
 
@@ -867,7 +943,7 @@ public Mono setLoggingLevel(LoggingLevel loggingLevel) {
 			return Mono.error(new IllegalArgumentException("Logging level must not be null"));
 		}
 
-		return this.initializer.withIntitialization("setting logging level", init -> {
+		return this.initializer.withInitialization("setting logging level", init -> {
 			if (init.initializeResult().capabilities().logging() == null) {
 				return Mono.error(new IllegalStateException("Server's Logging capabilities are not enabled!"));
 			}
@@ -876,15 +952,6 @@ public Mono setLoggingLevel(LoggingLevel loggingLevel) {
 		});
 	}
 
-	/**
-	 * Create a notification handler for progress notifications from the server. This
-	 * handler automatically distributes progress notifications to all registered
-	 * consumers.
-	 * @param progressConsumers List of consumers that will be notified when a progress
-	 * message is received. Each consumer receives the progress notification.
-	 * @return A NotificationHandler that processes progress notifications by distributing
-	 * the message to all registered consumers
-	 */
 	private NotificationHandler asyncProgressNotificationHandler(
 			List>> progressConsumers) {
 
@@ -924,7 +991,7 @@ void setProtocolVersions(List protocolVersions) {
 	 * @see McpSchema.CompleteResult
 	 */
 	public Mono completeCompletion(McpSchema.CompleteRequest completeRequest) {
-		return this.initializer.withIntitialization("complete completions", init -> init.mcpSession()
+		return this.initializer.withInitialization("complete completions", init -> init.mcpSession()
 			.sendRequest(McpSchema.METHOD_COMPLETION_COMPLETE, completeRequest, COMPLETION_COMPLETE_RESULT_TYPE_REF));
 	}
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
index 534879f2c..e39d43e27 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
@@ -13,6 +13,7 @@
 import java.util.function.Function;
 import java.util.function.Supplier;
 
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -99,6 +100,7 @@
  *
  * @author Christian Tzolov
  * @author Dariusz Jędrzejczyk
+ * @author Anurag Pant
  * @see McpAsyncClient
  * @see McpSyncClient
  * @see McpTransport
@@ -187,6 +189,10 @@ class SyncSpec {
 
 		private Supplier contextProvider = () -> McpTransportContext.EMPTY;
 
+		private JsonSchemaValidator jsonSchemaValidator;
+
+		private boolean enableCallToolSchemaCaching = false; // Default to false
+
 		private SyncSpec(McpClientTransport transport) {
 			Assert.notNull(transport, "Transport must not be null");
 			this.transport = transport;
@@ -429,6 +435,32 @@ public SyncSpec transportContextProvider(Supplier contextPr
 			return this;
 		}
 
+		/**
+		 * Add a {@link JsonSchemaValidator} to validate the JSON structure of the
+		 * structured output.
+		 * @param jsonSchemaValidator A validator to validate the JSON structure of the
+		 * structured output. Must not be null.
+		 * @return This builder for method chaining
+		 * @throws IllegalArgumentException if jsonSchemaValidator is null
+		 */
+		public SyncSpec jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			this.jsonSchemaValidator = jsonSchemaValidator;
+			return this;
+		}
+
+		/**
+		 * Enables automatic schema caching during callTool operations. When a tool's
+		 * output schema is not found in the cache, callTool will automatically fetch and
+		 * cache all tool schemas via listTools.
+		 * @param enableCallToolSchemaCaching true to enable, false to disable
+		 * @return This builder instance for method chaining
+		 */
+		public SyncSpec enableCallToolSchemaCaching(boolean enableCallToolSchemaCaching) {
+			this.enableCallToolSchemaCaching = enableCallToolSchemaCaching;
+			return this;
+		}
+
 		/**
 		 * Create an instance of {@link McpSyncClient} with the provided configurations or
 		 * sensible defaults.
@@ -438,13 +470,13 @@ public McpSyncClient build() {
 			McpClientFeatures.Sync syncFeatures = new McpClientFeatures.Sync(this.clientInfo, this.capabilities,
 					this.roots, this.toolsChangeConsumers, this.resourcesChangeConsumers, this.resourcesUpdateConsumers,
 					this.promptsChangeConsumers, this.loggingConsumers, this.progressConsumers, this.samplingHandler,
-					this.elicitationHandler);
+					this.elicitationHandler, this.enableCallToolSchemaCaching);
 
 			McpClientFeatures.Async asyncFeatures = McpClientFeatures.Async.fromSync(syncFeatures);
 
-			return new McpSyncClient(
-					new McpAsyncClient(transport, this.requestTimeout, this.initializationTimeout, asyncFeatures),
-					this.contextProvider);
+			return new McpSyncClient(new McpAsyncClient(transport, this.requestTimeout, this.initializationTimeout,
+					jsonSchemaValidator != null ? jsonSchemaValidator : JsonSchemaValidator.getDefault(),
+					asyncFeatures), this.contextProvider);
 		}
 
 	}
@@ -495,6 +527,10 @@ class AsyncSpec {
 
 		private Function> elicitationHandler;
 
+		private JsonSchemaValidator jsonSchemaValidator;
+
+		private boolean enableCallToolSchemaCaching = false; // Default to false
+
 		private AsyncSpec(McpClientTransport transport) {
 			Assert.notNull(transport, "Transport must not be null");
 			this.transport = transport;
@@ -741,17 +777,45 @@ public AsyncSpec progressConsumers(
 			return this;
 		}
 
+		/**
+		 * Sets the JSON schema validator to use for validating tool responses against
+		 * output schemas.
+		 * @param jsonSchemaValidator The validator to use. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if jsonSchemaValidator is null
+		 */
+		public AsyncSpec jsonSchemaValidator(JsonSchemaValidator jsonSchemaValidator) {
+			Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+			this.jsonSchemaValidator = jsonSchemaValidator;
+			return this;
+		}
+
+		/**
+		 * Enables automatic schema caching during callTool operations. When a tool's
+		 * output schema is not found in the cache, callTool will automatically fetch and
+		 * cache all tool schemas via listTools.
+		 * @param enableCallToolSchemaCaching true to enable, false to disable
+		 * @return This builder instance for method chaining
+		 */
+		public AsyncSpec enableCallToolSchemaCaching(boolean enableCallToolSchemaCaching) {
+			this.enableCallToolSchemaCaching = enableCallToolSchemaCaching;
+			return this;
+		}
+
 		/**
 		 * Create an instance of {@link McpAsyncClient} with the provided configurations
 		 * or sensible defaults.
 		 * @return a new instance of {@link McpAsyncClient}.
 		 */
 		public McpAsyncClient build() {
+			var jsonSchemaValidator = (this.jsonSchemaValidator != null) ? this.jsonSchemaValidator
+					: JsonSchemaValidator.getDefault();
 			return new McpAsyncClient(this.transport, this.requestTimeout, this.initializationTimeout,
+					jsonSchemaValidator,
 					new McpClientFeatures.Async(this.clientInfo, this.capabilities, this.roots,
 							this.toolsChangeConsumers, this.resourcesChangeConsumers, this.resourcesUpdateConsumers,
 							this.promptsChangeConsumers, this.loggingConsumers, this.progressConsumers,
-							this.samplingHandler, this.elicitationHandler));
+							this.samplingHandler, this.elicitationHandler, this.enableCallToolSchemaCaching));
 		}
 
 	}
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
index 3b6550765..127d53337 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java
@@ -62,6 +62,7 @@ class McpClientFeatures {
 	 * @param progressConsumers the progress consumers.
 	 * @param samplingHandler the sampling handler.
 	 * @param elicitationHandler the elicitation handler.
+	 * @param enableCallToolSchemaCaching whether to enable call tool schema caching.
 	 */
 	record Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
 			Map roots, List, Mono>> toolsChangeConsumers,
@@ -71,7 +72,8 @@ record Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 			List>> loggingConsumers,
 			List>> progressConsumers,
 			Function> samplingHandler,
-			Function> elicitationHandler) {
+			Function> elicitationHandler,
+			boolean enableCallToolSchemaCaching) {
 
 		/**
 		 * Create an instance and validate the arguments.
@@ -84,6 +86,7 @@ record Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 		 * @param progressConsumers the progress consumers.
 		 * @param samplingHandler the sampling handler.
 		 * @param elicitationHandler the elicitation handler.
+		 * @param enableCallToolSchemaCaching whether to enable call tool schema caching.
 		 */
 		public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
 				Map roots,
@@ -94,7 +97,8 @@ public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 				List>> loggingConsumers,
 				List>> progressConsumers,
 				Function> samplingHandler,
-				Function> elicitationHandler) {
+				Function> elicitationHandler,
+				boolean enableCallToolSchemaCaching) {
 
 			Assert.notNull(clientInfo, "Client info must not be null");
 			this.clientInfo = clientInfo;
@@ -113,6 +117,7 @@ public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 			this.progressConsumers = progressConsumers != null ? progressConsumers : List.of();
 			this.samplingHandler = samplingHandler;
 			this.elicitationHandler = elicitationHandler;
+			this.enableCallToolSchemaCaching = enableCallToolSchemaCaching;
 		}
 
 		/**
@@ -129,7 +134,7 @@ public Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities c
 				Function> elicitationHandler) {
 			this(clientInfo, clientCapabilities, roots, toolsChangeConsumers, resourcesChangeConsumers,
 					resourcesUpdateConsumers, promptsChangeConsumers, loggingConsumers, List.of(), samplingHandler,
-					elicitationHandler);
+					elicitationHandler, false);
 		}
 
 		/**
@@ -187,7 +192,8 @@ public static Async fromSync(Sync syncSpec) {
 
 			return new Async(syncSpec.clientInfo(), syncSpec.clientCapabilities(), syncSpec.roots(),
 					toolsChangeConsumers, resourcesChangeConsumers, resourcesUpdateConsumers, promptsChangeConsumers,
-					loggingConsumers, progressConsumers, samplingHandler, elicitationHandler);
+					loggingConsumers, progressConsumers, samplingHandler, elicitationHandler,
+					syncSpec.enableCallToolSchemaCaching);
 		}
 	}
 
@@ -205,6 +211,7 @@ public static Async fromSync(Sync syncSpec) {
 	 * @param progressConsumers the progress consumers.
 	 * @param samplingHandler the sampling handler.
 	 * @param elicitationHandler the elicitation handler.
+	 * @param enableCallToolSchemaCaching whether to enable call tool schema caching.
 	 */
 	public record Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
 			Map roots, List>> toolsChangeConsumers,
@@ -214,7 +221,8 @@ public record Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabili
 			List> loggingConsumers,
 			List> progressConsumers,
 			Function samplingHandler,
-			Function elicitationHandler) {
+			Function elicitationHandler,
+			boolean enableCallToolSchemaCaching) {
 
 		/**
 		 * Create an instance and validate the arguments.
@@ -229,6 +237,7 @@ public record Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabili
 		 * @param progressConsumers the progress consumers.
 		 * @param samplingHandler the sampling handler.
 		 * @param elicitationHandler the elicitation handler.
+		 * @param enableCallToolSchemaCaching whether to enable call tool schema caching.
 		 */
 		public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
 				Map roots, List>> toolsChangeConsumers,
@@ -238,7 +247,8 @@ public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities cl
 				List> loggingConsumers,
 				List> progressConsumers,
 				Function samplingHandler,
-				Function elicitationHandler) {
+				Function elicitationHandler,
+				boolean enableCallToolSchemaCaching) {
 
 			Assert.notNull(clientInfo, "Client info must not be null");
 			this.clientInfo = clientInfo;
@@ -257,6 +267,7 @@ public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities cl
 			this.progressConsumers = progressConsumers != null ? progressConsumers : List.of();
 			this.samplingHandler = samplingHandler;
 			this.elicitationHandler = elicitationHandler;
+			this.enableCallToolSchemaCaching = enableCallToolSchemaCaching;
 		}
 
 		/**
@@ -272,7 +283,7 @@ public Sync(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities cl
 				Function elicitationHandler) {
 			this(clientInfo, clientCapabilities, roots, toolsChangeConsumers, resourcesChangeConsumers,
 					resourcesUpdateConsumers, promptsChangeConsumers, loggingConsumers, List.of(), samplingHandler,
-					elicitationHandler);
+					elicitationHandler, false);
 		}
 	}
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 8186bb199..12835a57a 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -17,7 +17,6 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
-import com.fasterxml.jackson.annotation.JsonTypeInfo.As;
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.util.Assert;
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
index 1e015ca5e..c4157bc37 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
@@ -4,15 +4,14 @@
 
 package io.modelcontextprotocol.client;
 
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.spec.McpClientTransport;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Timeout;
 import org.testcontainers.containers.GenericContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
 
-import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
-import io.modelcontextprotocol.spec.McpClientTransport;
-
 @Timeout(15)
 public class HttpClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerPostInitializationHookTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerPostInitializationHookTests.java
new file mode 100644
index 000000000..6f7390f19
--- /dev/null
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerPostInitializationHookTests.java
@@ -0,0 +1,280 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.client;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Function;
+
+import io.modelcontextprotocol.client.LifecycleInitializer.Initialization;
+import io.modelcontextprotocol.spec.McpClientSession;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+import reactor.test.StepVerifier;
+import reactor.util.context.ContextView;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * Tests for {@link LifecycleInitializer} postInitializationHook functionality.
+ * 
+ * @author Christian Tzolov
+ */
+class LifecycleInitializerPostInitializationHookTests {
+
+	private static final Duration INITIALIZATION_TIMEOUT = Duration.ofSeconds(5);
+
+	private static final McpSchema.ClientCapabilities CLIENT_CAPABILITIES = McpSchema.ClientCapabilities.builder()
+		.build();
+
+	private static final McpSchema.Implementation CLIENT_INFO = new McpSchema.Implementation("test-client", "1.0.0");
+
+	private static final List PROTOCOL_VERSIONS = List.of("1.0.0", "2.0.0");
+
+	private static final McpSchema.InitializeResult MOCK_INIT_RESULT = new McpSchema.InitializeResult("2.0.0",
+			McpSchema.ServerCapabilities.builder().build(), new McpSchema.Implementation("test-server", "1.0.0"),
+			"Test instructions");
+
+	@Mock
+	private McpClientSession mockClientSession;
+
+	@Mock
+	private Function mockSessionSupplier;
+
+	@Mock
+	private Function> mockPostInitializationHook;
+
+	private LifecycleInitializer initializer;
+
+	@BeforeEach
+	void setUp() {
+		MockitoAnnotations.openMocks(this);
+
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenReturn(Mono.empty());
+		when(mockSessionSupplier.apply(any(ContextView.class))).thenReturn(mockClientSession);
+		when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()))
+			.thenReturn(Mono.just(MOCK_INIT_RESULT));
+		when(mockClientSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any()))
+			.thenReturn(Mono.empty());
+		when(mockClientSession.closeGracefully()).thenReturn(Mono.empty());
+
+		initializer = new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, PROTOCOL_VERSIONS,
+				INITIALIZATION_TIMEOUT, mockSessionSupplier, mockPostInitializationHook);
+	}
+
+	@Test
+	void shouldInvokePostInitializationHook() {
+		AtomicReference capturedInit = new AtomicReference<>();
+
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenAnswer(invocation -> {
+			capturedInit.set(invocation.getArgument(0));
+			return Mono.empty();
+		});
+
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
+			.expectNext(MOCK_INIT_RESULT)
+			.verifyComplete();
+
+		// Verify hook was called
+		verify(mockPostInitializationHook, times(1)).apply(any(Initialization.class));
+
+		// Verify the hook received correct initialization data
+		assertThat(capturedInit.get()).isNotNull();
+		assertThat(capturedInit.get().mcpSession()).isEqualTo(mockClientSession);
+		assertThat(capturedInit.get().initializeResult()).isEqualTo(MOCK_INIT_RESULT);
+	}
+
+	@Test
+	void shouldInvokePostInitializationHookOnlyOnce() {
+		// First initialization
+		StepVerifier.create(initializer.withInitialization("test1", init -> Mono.just("result1")))
+			.expectNext("result1")
+			.verifyComplete();
+
+		// Second call should reuse initialization and NOT call hook again
+		StepVerifier.create(initializer.withInitialization("test2", init -> Mono.just("result2")))
+			.expectNext("result2")
+			.verifyComplete();
+
+		// Hook should only be called once
+		verify(mockPostInitializationHook, times(1)).apply(any(Initialization.class));
+	}
+
+	@Test
+	void shouldInvokePostInitializationHookOnlyOnceWithConcurrentRequests() {
+		AtomicInteger hookInvocationCount = new AtomicInteger(0);
+
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenAnswer(invocation -> {
+			hookInvocationCount.incrementAndGet();
+			return Mono.empty();
+		});
+
+		// Start multiple concurrent initializations
+		Mono init1 = initializer.withInitialization("test1", init -> Mono.just("result1"))
+			.subscribeOn(Schedulers.parallel());
+		Mono init2 = initializer.withInitialization("test2", init -> Mono.just("result2"))
+			.subscribeOn(Schedulers.parallel());
+		Mono init3 = initializer.withInitialization("test3", init -> Mono.just("result3"))
+			.subscribeOn(Schedulers.parallel());
+
+		// TODO: can we assume the order of results?
+		StepVerifier.create(Mono.zip(init1, init2, init3)).assertNext(tuple -> {
+			assertThat(tuple.getT1()).isEqualTo("result1");
+			assertThat(tuple.getT2()).isEqualTo("result2");
+			assertThat(tuple.getT3()).isEqualTo("result3");
+		}).verifyComplete();
+
+		// Hook should only be called once despite concurrent requests
+		assertThat(hookInvocationCount.get()).isEqualTo(1);
+	}
+
+	@Test
+	void shouldFailInitializationWhenPostInitializationHookFails() {
+		RuntimeException hookError = new RuntimeException("Post-initialization hook failed");
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenReturn(Mono.error(hookError));
+
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
+			.expectErrorMatches(ex -> ex instanceof RuntimeException && ex.getCause() == hookError)
+			.verify();
+
+		// Verify initialization was not completed
+		assertThat(initializer.isInitialized()).isFalse();
+		assertThat(initializer.currentInitializationResult()).isNull();
+
+		// Verify the hook was called
+		verify(mockPostInitializationHook, times(1)).apply(any(Initialization.class));
+	}
+
+	@Test
+	void shouldNotInvokePostInitializationHookWhenInitializationFails() {
+		when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()))
+			.thenReturn(Mono.error(new RuntimeException("Initialization failed")));
+
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
+			.expectError(RuntimeException.class)
+			.verify();
+
+		// Hook should NOT be called when initialization fails
+		verify(mockPostInitializationHook, never()).apply(any(Initialization.class));
+	}
+
+	@Test
+	void shouldNotInvokePostInitializationHookWhenNotificationFails() {
+		when(mockClientSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any()))
+			.thenReturn(Mono.error(new RuntimeException("Notification failed")));
+
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
+			.expectError(RuntimeException.class)
+			.verify();
+
+		// Hook should NOT be called when notification fails
+		verify(mockPostInitializationHook, never()).apply(any(Initialization.class));
+	}
+
+	@Test
+	void shouldInvokePostInitializationHookAgainAfterReinitialization() {
+		AtomicInteger hookInvocationCount = new AtomicInteger(0);
+
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenAnswer(invocation -> {
+			hookInvocationCount.incrementAndGet();
+			return Mono.empty();
+		});
+
+		// First initialization
+		StepVerifier.create(initializer.withInitialization("test1", init -> Mono.just("result1")))
+			.expectNext("result1")
+			.verifyComplete();
+
+		assertThat(hookInvocationCount.get()).isEqualTo(1);
+
+		// Simulate transport session exception to trigger re-initialization
+		initializer.handleException(new McpTransportSessionNotFoundException("Session lost"));
+
+		// Hook should be called twice (once for each initialization)
+		assertThat(hookInvocationCount.get()).isEqualTo(2);
+	}
+
+	@Test
+	void shouldAllowPostInitializationHookToPerformAsyncOperations() {
+		AtomicInteger operationCount = new AtomicInteger(0);
+
+		when(mockPostInitializationHook.apply(any(Initialization.class)))
+			.thenReturn(Mono.fromRunnable(() -> operationCount.incrementAndGet()).then());
+
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
+			.expectNext(MOCK_INIT_RESULT)
+			.verifyComplete();
+
+		// Verify the async operation was executed
+		assertThat(operationCount.get()).isEqualTo(1);
+		verify(mockPostInitializationHook, times(1)).apply(any(Initialization.class));
+	}
+
+	@Test
+	void shouldProvideCorrectInitializationDataToHook() {
+		AtomicReference capturedSession = new AtomicReference<>();
+		AtomicReference capturedResult = new AtomicReference<>();
+
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenAnswer(invocation -> {
+			Initialization init = invocation.getArgument(0);
+			capturedSession.set(init.mcpSession());
+			capturedResult.set(init.initializeResult());
+			return Mono.empty();
+		});
+
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
+			.expectNext(MOCK_INIT_RESULT)
+			.verifyComplete();
+
+		// Verify the hook received the correct session and result
+		assertThat(capturedSession.get()).isEqualTo(mockClientSession);
+		assertThat(capturedResult.get()).isEqualTo(MOCK_INIT_RESULT);
+		assertThat(capturedResult.get().protocolVersion()).isEqualTo("2.0.0");
+		assertThat(capturedResult.get().serverInfo().name()).isEqualTo("test-server");
+	}
+
+	@Test
+	void shouldInvokePostInitializationHookAfterSuccessfulInitialization() {
+		AtomicReference notificationSent = new AtomicReference<>(false);
+		AtomicReference hookCalledAfterNotification = new AtomicReference<>(false);
+
+		when(mockClientSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any()))
+			.thenAnswer(invocation -> {
+				notificationSent.set(true);
+				return Mono.empty();
+			});
+
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenAnswer(invocation -> {
+			// Due to flatMap chaining in doInitialize, if the hook is called,
+			// the notification must have been sent first
+			hookCalledAfterNotification.set(notificationSent.get());
+			return Mono.empty();
+		});
+
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
+			.expectNext(MOCK_INIT_RESULT)
+			.verifyComplete();
+
+		// Verify the hook was called and notification was already sent at that point
+		assertThat(hookCalledAfterNotification.get()).isTrue();
+		verify(mockClientSession).sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any());
+		verify(mockPostInitializationHook).apply(any(Initialization.class));
+	}
+
+}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
index 19de14c24..787ee9480 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/LifecycleInitializerTests.java
@@ -10,14 +10,14 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 
+import io.modelcontextprotocol.client.LifecycleInitializer.Initialization;
+import io.modelcontextprotocol.spec.McpClientSession;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.mockito.Mock;
 import org.mockito.MockitoAnnotations;
-
-import io.modelcontextprotocol.spec.McpClientSession;
-import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import reactor.core.publisher.Mono;
 import reactor.core.scheduler.Schedulers;
 import reactor.test.StepVerifier;
@@ -58,12 +58,16 @@ class LifecycleInitializerTests {
 	@Mock
 	private Function mockSessionSupplier;
 
+	@Mock
+	private Function> mockPostInitializationHook;
+
 	private LifecycleInitializer initializer;
 
 	@BeforeEach
 	void setUp() {
 		MockitoAnnotations.openMocks(this);
 
+		when(mockPostInitializationHook.apply(any(Initialization.class))).thenReturn(Mono.empty());
 		when(mockSessionSupplier.apply(any(ContextView.class))).thenReturn(mockClientSession);
 		when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()))
 			.thenReturn(Mono.just(MOCK_INIT_RESULT));
@@ -72,45 +76,45 @@ void setUp() {
 		when(mockClientSession.closeGracefully()).thenReturn(Mono.empty());
 
 		initializer = new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, PROTOCOL_VERSIONS,
-				INITIALIZATION_TIMEOUT, mockSessionSupplier);
+				INITIALIZATION_TIMEOUT, mockSessionSupplier, mockPostInitializationHook);
 	}
 
 	@Test
 	void constructorShouldValidateParameters() {
 		assertThatThrownBy(() -> new LifecycleInitializer(null, CLIENT_INFO, PROTOCOL_VERSIONS, INITIALIZATION_TIMEOUT,
-				mockSessionSupplier))
+				mockSessionSupplier, mockPostInitializationHook))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Client capabilities must not be null");
 
 		assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, null, PROTOCOL_VERSIONS,
-				INITIALIZATION_TIMEOUT, mockSessionSupplier))
+				INITIALIZATION_TIMEOUT, mockSessionSupplier, mockPostInitializationHook))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Client info must not be null");
 
 		assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, null,
-				INITIALIZATION_TIMEOUT, mockSessionSupplier))
+				INITIALIZATION_TIMEOUT, mockSessionSupplier, mockPostInitializationHook))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Protocol versions must not be empty");
 
 		assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, List.of(),
-				INITIALIZATION_TIMEOUT, mockSessionSupplier))
+				INITIALIZATION_TIMEOUT, mockSessionSupplier, mockPostInitializationHook))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Protocol versions must not be empty");
 
 		assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, PROTOCOL_VERSIONS, null,
-				mockSessionSupplier))
+				mockSessionSupplier, mockPostInitializationHook))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Initialization timeout must not be null");
 
 		assertThatThrownBy(() -> new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO, PROTOCOL_VERSIONS,
-				INITIALIZATION_TIMEOUT, null))
+				INITIALIZATION_TIMEOUT, null, mockPostInitializationHook))
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Session supplier must not be null");
 	}
 
 	@Test
 	void shouldInitializeSuccessfully() {
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.assertNext(result -> {
 				assertThat(result).isEqualTo(MOCK_INIT_RESULT);
 				assertThat(initializer.isInitialized()).isTrue();
@@ -132,7 +136,7 @@ void shouldUseLatestProtocolVersionInInitializeRequest() {
 			return Mono.just(MOCK_INIT_RESULT);
 		});
 
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.assertNext(result -> {
 				assertThat(capturedRequest.get().protocolVersion()).isEqualTo("2.0.0"); // Latest
 																						// version
@@ -152,7 +156,7 @@ void shouldFailForUnsupportedProtocolVersion() {
 		when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()))
 			.thenReturn(Mono.just(unsupportedResult));
 
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectError(RuntimeException.class)
 			.verify();
 
@@ -167,13 +171,13 @@ void shouldTimeoutOnSlowInitialization() {
 		Duration SLOW_RESPONSE_DELAY = Duration.ofSeconds(5);
 
 		LifecycleInitializer shortTimeoutInitializer = new LifecycleInitializer(CLIENT_CAPABILITIES, CLIENT_INFO,
-				PROTOCOL_VERSIONS, INITIALIZE_TIMEOUT, mockSessionSupplier);
+				PROTOCOL_VERSIONS, INITIALIZE_TIMEOUT, mockSessionSupplier, mockPostInitializationHook);
 
 		when(mockClientSession.sendRequest(eq(McpSchema.METHOD_INITIALIZE), any(), any()))
 			.thenReturn(Mono.just(MOCK_INIT_RESULT).delayElement(SLOW_RESPONSE_DELAY, virtualTimeScheduler));
 
 		StepVerifier
-			.withVirtualTime(() -> shortTimeoutInitializer.withIntitialization("test",
+			.withVirtualTime(() -> shortTimeoutInitializer.withInitialization("test",
 					init -> Mono.just(init.initializeResult())), () -> virtualTimeScheduler, Long.MAX_VALUE)
 			.expectSubscription()
 			.expectNoEvent(INITIALIZE_TIMEOUT)
@@ -184,12 +188,12 @@ void shouldTimeoutOnSlowInitialization() {
 	@Test
 	void shouldReuseExistingInitialization() {
 		// First initialization
-		StepVerifier.create(initializer.withIntitialization("test1", init -> Mono.just("result1")))
+		StepVerifier.create(initializer.withInitialization("test1", init -> Mono.just("result1")))
 			.expectNext("result1")
 			.verifyComplete();
 
 		// Second call should reuse the same initialization
-		StepVerifier.create(initializer.withIntitialization("test2", init -> Mono.just("result2")))
+		StepVerifier.create(initializer.withInitialization("test2", init -> Mono.just("result2")))
 			.expectNext("result2")
 			.verifyComplete();
 
@@ -209,11 +213,11 @@ void shouldHandleConcurrentInitializationRequests() {
 
 		// Start multiple concurrent initializations using subscribeOn with parallel
 		// scheduler
-		Mono init1 = initializer.withIntitialization("test1", init -> Mono.just("result1"))
+		Mono init1 = initializer.withInitialization("test1", init -> Mono.just("result1"))
 			.subscribeOn(Schedulers.parallel());
-		Mono init2 = initializer.withIntitialization("test2", init -> Mono.just("result2"))
+		Mono init2 = initializer.withInitialization("test2", init -> Mono.just("result2"))
 			.subscribeOn(Schedulers.parallel());
-		Mono init3 = initializer.withIntitialization("test3", init -> Mono.just("result3"))
+		Mono init3 = initializer.withInitialization("test3", init -> Mono.just("result3"))
 			.subscribeOn(Schedulers.parallel());
 
 		StepVerifier.create(Mono.zip(init1, init2, init3)).assertNext(tuple -> {
@@ -235,7 +239,7 @@ void shouldHandleInitializationFailure() {
 			// succeeds on the second call
 			.thenReturn(Mono.just(MOCK_INIT_RESULT));
 
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectError(RuntimeException.class)
 			.verify();
 
@@ -244,7 +248,7 @@ void shouldHandleInitializationFailure() {
 
 		// The initializer can recover from previous errors
 		StepVerifier
-			.create(initializer.withIntitialization("successful init", init -> Mono.just(init.initializeResult())))
+			.create(initializer.withInitialization("successful init", init -> Mono.just(init.initializeResult())))
 			.expectNext(MOCK_INIT_RESULT)
 			.verifyComplete();
 
@@ -255,7 +259,7 @@ void shouldHandleInitializationFailure() {
 	@Test
 	void shouldHandleTransportSessionNotFoundException() {
 		// successful initialization first
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectNext(MOCK_INIT_RESULT)
 			.verifyComplete();
 
@@ -277,7 +281,7 @@ void shouldHandleTransportSessionNotFoundException() {
 	@Test
 	void shouldHandleOtherExceptions() {
 		// Simulate a successful initialization first
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectNext(MOCK_INIT_RESULT)
 			.verifyComplete();
 
@@ -295,7 +299,7 @@ void shouldHandleOtherExceptions() {
 
 	@Test
 	void shouldCloseGracefully() {
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectNext(MOCK_INIT_RESULT)
 			.verifyComplete();
 
@@ -307,7 +311,7 @@ void shouldCloseGracefully() {
 
 	@Test
 	void shouldCloseImmediately() {
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectNext(MOCK_INIT_RESULT)
 			.verifyComplete();
 
@@ -342,7 +346,7 @@ void shouldSetProtocolVersionsForTesting() {
 					new McpSchema.Implementation("test-server", "1.0.0"), "Test instructions"));
 		});
 
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.assertNext(result -> {
 				// Latest from new versions
 				assertThat(capturedRequest.get().protocolVersion()).isEqualTo("4.0.0");
@@ -363,7 +367,7 @@ void shouldPassContextToSessionSupplier() {
 		});
 
 		StepVerifier
-			.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult()))
+			.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult()))
 				.contextWrite(Context.of(contextKey, contextValue)))
 			.expectNext(MOCK_INIT_RESULT)
 			.verifyComplete();
@@ -374,7 +378,7 @@ void shouldPassContextToSessionSupplier() {
 
 	@Test
 	void shouldProvideAccessToMcpSessionAndInitializeResult() {
-		StepVerifier.create(initializer.withIntitialization("test", init -> {
+		StepVerifier.create(initializer.withInitialization("test", init -> {
 			assertThat(init.mcpSession()).isEqualTo(mockClientSession);
 			assertThat(init.initializeResult()).isEqualTo(MOCK_INIT_RESULT);
 			return Mono.just("success");
@@ -386,7 +390,7 @@ void shouldHandleNotificationFailure() {
 		when(mockClientSession.sendNotification(eq(McpSchema.METHOD_NOTIFICATION_INITIALIZED), any()))
 			.thenReturn(Mono.error(new RuntimeException("Notification failed")));
 
-		StepVerifier.create(initializer.withIntitialization("test", init -> Mono.just(init.initializeResult())))
+		StepVerifier.create(initializer.withInitialization("test", init -> Mono.just(init.initializeResult())))
 			.expectError(RuntimeException.class)
 			.verify();
 
@@ -403,7 +407,7 @@ void shouldReturnNullWhenNotInitialized() {
 	@Test
 	void shouldReinitializeAfterTransportSessionException() {
 		// First initialization
-		StepVerifier.create(initializer.withIntitialization("test1", init -> Mono.just("result1")))
+		StepVerifier.create(initializer.withInitialization("test1", init -> Mono.just("result1")))
 			.expectNext("result1")
 			.verifyComplete();
 
@@ -411,7 +415,7 @@ void shouldReinitializeAfterTransportSessionException() {
 		initializer.handleException(new McpTransportSessionNotFoundException("Session lost"));
 
 		// Should be able to initialize again
-		StepVerifier.create(initializer.withIntitialization("test2", init -> Mono.just("result2")))
+		StepVerifier.create(initializer.withInitialization("test2", init -> Mono.just("result2")))
 			.expectNext("result2")
 			.verifyComplete();
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
index 3e29e89ab..970d8f257 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
@@ -10,12 +10,20 @@
 import io.modelcontextprotocol.spec.ProtocolVersions;
 
 import org.junit.jupiter.api.Test;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+
 import reactor.core.publisher.Mono;
+import reactor.test.StepVerifier;
 
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 
 import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 
 class McpAsyncClientTests {
@@ -24,6 +32,7 @@ class McpAsyncClientTests {
 			"1.0.0");
 
 	public static final McpSchema.ServerCapabilities MOCK_SERVER_CAPABILITIES = McpSchema.ServerCapabilities.builder()
+		.tools(true)
 		.build();
 
 	public static final McpSchema.InitializeResult MOCK_INIT_RESULT = new McpSchema.InitializeResult(
@@ -31,6 +40,91 @@ class McpAsyncClientTests {
 
 	private static final String CONTEXT_KEY = "context.key";
 
+	private McpClientTransport createMockTransportForToolValidation(boolean hasOutputSchema, boolean invalidOutput)
+			throws JsonProcessingException {
+
+		// Create tool with or without output schema
+		Map inputSchemaMap = Map.of("type", "object", "properties",
+				Map.of("expression", Map.of("type", "string")), "required", List.of("expression"));
+
+		McpSchema.JsonSchema inputSchema = new McpSchema.JsonSchema("object", inputSchemaMap, null, null, null, null);
+		McpSchema.Tool.Builder toolBuilder = McpSchema.Tool.builder()
+			.name("calculator")
+			.description("Performs mathematical calculations")
+			.inputSchema(inputSchema);
+
+		if (hasOutputSchema) {
+			Map outputSchema = Map.of("type", "object", "properties",
+					Map.of("result", Map.of("type", "number"), "operation", Map.of("type", "string")), "required",
+					List.of("result", "operation"));
+			toolBuilder.outputSchema(outputSchema);
+		}
+
+		McpSchema.Tool calculatorTool = toolBuilder.build();
+		McpSchema.ListToolsResult mockToolsResult = new McpSchema.ListToolsResult(List.of(calculatorTool), null);
+
+		// Create call tool result - valid or invalid based on parameter
+		Map structuredContent = invalidOutput ? Map.of("result", "5", "operation", "add")
+				: Map.of("result", 5, "operation", "add");
+
+		McpSchema.CallToolResult mockCallToolResult = McpSchema.CallToolResult.builder()
+			.addTextContent("Calculation result")
+			.structuredContent(structuredContent)
+			.build();
+
+		return new McpClientTransport() {
+			Function, Mono> handler;
+
+			@Override
+			public Mono connect(
+					Function, Mono> handler) {
+				this.handler = handler;
+				return Mono.empty();
+			}
+
+			@Override
+			public Mono closeGracefully() {
+				return Mono.empty();
+			}
+
+			@Override
+			public Mono sendMessage(McpSchema.JSONRPCMessage message) {
+				if (!(message instanceof McpSchema.JSONRPCRequest request)) {
+					return Mono.empty();
+				}
+
+				McpSchema.JSONRPCResponse response;
+				if (McpSchema.METHOD_INITIALIZE.equals(request.method())) {
+					response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), MOCK_INIT_RESULT,
+							null);
+				}
+				else if (McpSchema.METHOD_TOOLS_LIST.equals(request.method())) {
+					response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), mockToolsResult,
+							null);
+				}
+				else if (McpSchema.METHOD_TOOLS_CALL.equals(request.method())) {
+					response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
+							mockCallToolResult, null);
+				}
+				else {
+					return Mono.empty();
+				}
+
+				return handler.apply(Mono.just(response)).then();
+			}
+
+			@Override
+			public  T unmarshalFrom(Object data, TypeRef typeRef) {
+				return JSON_MAPPER.convertValue(data, new TypeRef<>() {
+					@Override
+					public java.lang.reflect.Type getType() {
+						return typeRef.getType();
+					}
+				});
+			}
+		};
+	}
+
 	@Test
 	void validateContextPassedToTransportConnect() {
 		McpClientTransport transport = new McpClientTransport() {
@@ -87,4 +181,64 @@ public java.lang.reflect.Type getType() {
 		}).doesNotThrowAnyException();
 	}
 
+	@Test
+	void testCallToolWithOutputSchemaValidationSuccess() throws JsonProcessingException {
+		McpClientTransport transport = createMockTransportForToolValidation(true, false);
+
+		McpAsyncClient client = McpClient.async(transport).enableCallToolSchemaCaching(true).build();
+
+		StepVerifier.create(client.initialize()).expectNextMatches(Objects::nonNull).verifyComplete();
+
+		StepVerifier.create(client.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3"))))
+			.expectNextMatches(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.isError()).isFalse();
+				assertThat(response.structuredContent()).isInstanceOf(Map.class);
+				assertThat((Map) response.structuredContent()).hasSize(2);
+				assertThat(response.content()).hasSize(1);
+				return true;
+			})
+			.verifyComplete();
+
+		StepVerifier.create(client.closeGracefully()).verifyComplete();
+	}
+
+	@Test
+	void testCallToolWithNoOutputSchemaSuccess() throws JsonProcessingException {
+		McpClientTransport transport = createMockTransportForToolValidation(false, false);
+
+		McpAsyncClient client = McpClient.async(transport).enableCallToolSchemaCaching(true).build();
+
+		StepVerifier.create(client.initialize()).expectNextMatches(Objects::nonNull).verifyComplete();
+
+		StepVerifier.create(client.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3"))))
+			.expectNextMatches(response -> {
+				assertThat(response).isNotNull();
+				assertThat(response.isError()).isFalse();
+				assertThat(response.structuredContent()).isInstanceOf(Map.class);
+				assertThat((Map) response.structuredContent()).hasSize(2);
+				assertThat(response.content()).hasSize(1);
+				return true;
+			})
+			.verifyComplete();
+
+		StepVerifier.create(client.closeGracefully()).verifyComplete();
+	}
+
+	@Test
+	void testCallToolWithOutputSchemaValidationFailure() throws JsonProcessingException {
+		McpClientTransport transport = createMockTransportForToolValidation(true, true);
+
+		McpAsyncClient client = McpClient.async(transport).enableCallToolSchemaCaching(true).build();
+
+		StepVerifier.create(client.initialize()).expectNextMatches(Objects::nonNull).verifyComplete();
+
+		StepVerifier.create(client.callTool(new McpSchema.CallToolRequest("calculator", Map.of("expression", "2 + 3"))))
+			.expectErrorMatches(ex -> ex instanceof IllegalArgumentException
+					&& ex.getMessage().contains("Tool call result validation failed"))
+			.verify();
+
+		StepVerifier.create(client.closeGracefully()).verifyComplete();
+	}
+
 }
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
index 3feb1d05c..a94b9b6a7 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpClientProtocolVersionTests.java
@@ -8,9 +8,9 @@
 import java.util.List;
 
 import io.modelcontextprotocol.MockMcpClientTransport;
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
@@ -22,7 +22,7 @@
  */
 class McpClientProtocolVersionTests {
 
-	private static final Duration REQUEST_TIMEOUT = Duration.ofSeconds(30);
+	private static final Duration REQUEST_TIMEOUT = Duration.ofSeconds(300);
 
 	private static final McpSchema.Implementation CLIENT_INFO = new McpSchema.Implementation("test-client", "1.0.0");
 
@@ -46,13 +46,12 @@ void shouldUseLatestVersionByDefault() {
 				assertThat(initRequest.protocolVersion()).isEqualTo(transport.protocolVersions().get(0));
 
 				transport.simulateIncomingMessage(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
-						new McpSchema.InitializeResult(protocolVersion, null,
+						new McpSchema.InitializeResult(protocolVersion, ServerCapabilities.builder().build(),
 								new McpSchema.Implementation("test-server", "1.0.0"), null),
 						null));
 			}).assertNext(result -> {
 				assertThat(result.protocolVersion()).isEqualTo(protocolVersion);
 			}).verifyComplete();
-
 		}
 		finally {
 			// Ensure cleanup happens even if test fails
@@ -81,7 +80,7 @@ void shouldNegotiateSpecificVersion() {
 				assertThat(initRequest.protocolVersion()).isIn(List.of(oldVersion, McpSchema.LATEST_PROTOCOL_VERSION));
 
 				transport.simulateIncomingMessage(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
-						new McpSchema.InitializeResult(oldVersion, null,
+						new McpSchema.InitializeResult(oldVersion, ServerCapabilities.builder().build(),
 								new McpSchema.Implementation("test-server", "1.0.0"), null),
 						null));
 			}).assertNext(result -> {
@@ -110,7 +109,7 @@ void shouldFailForUnsupportedVersion() {
 				assertThat(request.params()).isInstanceOf(McpSchema.InitializeRequest.class);
 
 				transport.simulateIncomingMessage(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
-						new McpSchema.InitializeResult(unsupportedVersion, null,
+						new McpSchema.InitializeResult(unsupportedVersion, ServerCapabilities.builder().build(),
 								new McpSchema.Implementation("test-server", "1.0.0"), null),
 						null));
 			}).expectError(RuntimeException.class).verify();
@@ -143,7 +142,7 @@ void shouldUseHighestVersionWhenMultipleSupported() {
 				assertThat(initRequest.protocolVersion()).isEqualTo(latestVersion);
 
 				transport.simulateIncomingMessage(new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(),
-						new McpSchema.InitializeResult(latestVersion, null,
+						new McpSchema.InitializeResult(latestVersion, ServerCapabilities.builder().build(),
 								new McpSchema.Implementation("test-server", "1.0.0"), null),
 						null));
 			}).assertNext(result -> {

From c734b2a5c120f43c99ff0d3cd0ec43de917b6610 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 2 Oct 2025 00:03:36 +0100
Subject: [PATCH 088/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       |  2 +-
 mcp-core/pom.xml                      |  6 +++---
 mcp-json-jackson2/pom.xml             |  4 ++--
 mcp-json/pom.xml                      |  2 +-
 mcp-spring/mcp-spring-webflux/pom.xml |  8 ++++----
 mcp-spring/mcp-spring-webmvc/pom.xml  | 10 +++++-----
 mcp-test/pom.xml                      |  4 ++--
 mcp/pom.xml                           |  6 +++---
 pom.xml                               |  2 +-
 9 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 6b1027a21..3c83afda3 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.14.0-SNAPSHOT
+        0.15.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-core/pom.xml b/mcp-core/pom.xml
index 8637303fe..5681385b6 100644
--- a/mcp-core/pom.xml
+++ b/mcp-core/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.14.0-SNAPSHOT
+		0.15.0-SNAPSHOT
 	
 	mcp-core
 	jar
@@ -68,7 +68,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.14.0-SNAPSHOT
+            0.15.0-SNAPSHOT
         
 
 		
@@ -101,7 +101,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.14.0-SNAPSHOT
+            0.15.0-SNAPSHOT
             test
         
 
diff --git a/mcp-json-jackson2/pom.xml b/mcp-json-jackson2/pom.xml
index b3d0a16de..75569c78e 100644
--- a/mcp-json-jackson2/pom.xml
+++ b/mcp-json-jackson2/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.14.0-SNAPSHOT
+		0.15.0-SNAPSHOT
 	
 	mcp-json-jackson2
 	jar
@@ -37,7 +37,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.14.0-SNAPSHOT
+            0.15.0-SNAPSHOT
         
         
             com.fasterxml.jackson.core
diff --git a/mcp-json/pom.xml b/mcp-json/pom.xml
index ebbc90142..790b056c6 100644
--- a/mcp-json/pom.xml
+++ b/mcp-json/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.14.0-SNAPSHOT
+		0.15.0-SNAPSHOT
 	
 	mcp-json
 	jar
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 5a96e609d..785ebd746 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.14.0-SNAPSHOT
+		0.15.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,19 +25,19 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.14.0-SNAPSHOT
+            0.15.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index e59c94c22..3dc0e13f9 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.14.0-SNAPSHOT
+		0.15.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,13 +25,13 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.14.0-SNAPSHOT
+            0.15.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 		
 
 		
@@ -43,14 +43,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 			test
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index cbaabdada..27560e10e 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.14.0-SNAPSHOT
+		0.15.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 492bd447d..412f7dc6b 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.14.0-SNAPSHOT
+		0.15.0-SNAPSHOT
 	
 	mcp
 	jar
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-json-jackson2
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-core
-			0.14.0-SNAPSHOT
+			0.15.0-SNAPSHOT
 		
 	
 
diff --git a/pom.xml b/pom.xml
index a5fd98b7f..f17b2b61b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.14.0-SNAPSHOT
+	0.15.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From 8a0eb130ad8f9ef74124dee358ecc34096d57ae9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dariusz=20J=C4=99drzejczyk?=
 
Date: Wed, 1 Oct 2025 13:50:55 +0200
Subject: [PATCH 089/125] Add section describing our architectural and design
 choices (#595)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Adib Saikali 
Signed-off-by: Dariusz Jędrzejczyk 
---
 README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/README.md b/README.md
index 39ba13926..4ac7e8d5b 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,133 @@ Please follow the [Contributing Guidelines](CONTRIBUTING.md).
 - [Issue Tracker](https://github.com/modelcontextprotocol/java-sdk/issues)
 - [CI/CD](https://github.com/modelcontextprotocol/java-sdk/actions)
 
+## Architecture and Design Decisions
+
+### Introduction
+
+Building a general-purpose MCP Java SDK requires making technology decisions in areas where the JDK provides limited or no support. The Java ecosystem is powerful but fragmented: multiple valid approaches exist, each with strong communities.
+Our goal is not to prescribe "the one true way," but to provide a reference implementation of the MCP specification that is:
+
+* **Pragmatic** – makes developers productive quickly
+* **Interoperable** – aligns with widely used libraries and practices
+* **Pluggable** – allows alternatives where projects prefer different stacks
+* **Grounded in team familiarity** – we chose technologies the team can be productive with today, while remaining open to community contributions that broaden the SDK
+
+### Key Choices and Considerations
+
+The SDK had to make decisions in the following areas:
+
+1. **JSON serialization** – mapping between JSON and Java types
+
+2. **Programming model** – supporting asynchronous processing, cancellation, and streaming while staying simple for blocking use cases
+
+3. **Observability** – logging and enabling integration with metrics/tracing
+
+4. **Remote clients and servers** – supporting both consuming MCP servers (client transport) and exposing MCP endpoints (server transport with authorization)
+
+The following sections explain what we chose, why it made sense, and how the choices align with the SDK's goals.
+
+### 1. JSON Serialization
+
+* **SDK Choice**: Jackson for JSON serialization and deserialization, behind an SDK abstraction (`mcp-json`)
+
+* **Why**: Jackson is widely adopted across the Java ecosystem, provides strong performance and a mature annotation model, and is familiar to the SDK team and many potential contributors.
+
+* **How we expose it**: Public APIs use a zero-dependency abstraction (`mcp-json`). Jackson is shipped as the default implementation (`mcp-jackson2`), but alternatives can be plugged in.
+
+* **How it fits the SDK**: This offers a pragmatic default while keeping flexibility for projects that prefer different JSON libraries.
+
+### 2. Programming Model
+
+* **SDK Choice**: Reactive Streams for public APIs, with Project Reactor as the internal implementation and a synchronous facade for blocking use cases
+
+* **Why**: MCP builds on JSON-RPC's asynchronous nature and defines a bidirectional protocol on top of it, enabling asynchronous and streaming interactions. MCP explicitly supports:
+
+    * Multiple in-flight requests and responses
+    * Notifications that do not expect a reply
+    * STDIO transports for inter-process communication using pipes
+    * Streaming transports such as Server-Sent Events and Streamable HTTP
+
+    These requirements call for a programming model more powerful than single-result futures like `CompletableFuture`.
+
+    * **Reactive Streams: the Community Standard**
+
+        Reactive Streams is a small Java specification that standardizes asynchronous stream processing with backpressure. It defines four minimal interfaces (Publisher, Subscriber, Subscription, and Processor). These interfaces are widely recognized as the standard contract for async, non-blocking pipelines in Java.
+
+    * **Reactive Streams Implementation**
+
+        The SDK uses Project Reactor as its implementation of the Reactive Streams specification. Reactor is mature, widely adopted, provides rich operators, and integrates well with observability through context propagation. Team familiarity also allowed us to deliver a solid foundation quickly.
+        We plan to convert the public API to only expose Reactive Streams interfaces. By defining the public API in terms of Reactive Streams interfaces and using Reactor internally, the SDK stays standards-based while benefiting from a practical, production-ready implementation.
+
+    * **Synchronous Facade in the SDK**
+
+        Not all MCP use cases require streaming pipelines. Many scenarios are as simple as "send a request and block until I get the result."
+        To support this, the SDK provides a synchronous facade layered on top of the reactive core. Developers can stay in a blocking model when it's enough, while still having access to asynchronous streaming when needed.
+
+* **How it fits the SDK**: This design balances scalability, approachability, and future evolution such as Virtual Threads and Structured Concurrency in upcoming JDKs.
+
+### 3. Observability
+
+* **SDK Choice**: SLF4J for logging; Reactor Context for observability propagation
+
+* **Why**: SLF4J is the de facto logging facade in Java, with broad compatibility. Reactor Context enables propagation of observability data such as correlation IDs and tracing state across async boundaries. This ensures interoperability with modern observability frameworks.
+
+* **How we expose it**: Public APIs log through SLF4J only, with no backend included. Observability metadata flows through Reactor pipelines. The SDK itself does not ship metrics or tracing implementations.
+
+* **How it fits the SDK**: This provides reliable logging by default and seamless integration with Micrometer, OpenTelemetry, or similar systems for metrics and tracing.
+
+### 4. Remote MCP Clients and Servers
+
+MCP supports both clients (applications consuming MCP servers) and servers (applications exposing MCP endpoints). The SDK provides support for both sides.
+
+#### Client Transport in the SDK
+
+* **SDK Choice**: JDK HttpClient (Java 11+) as the default client, with optional Spring WebClient support
+
+* **Why**: The JDK HttpClient is built-in, portable, and supports streaming responses. This keeps the default lightweight with no extra dependencies. Spring WebClient support is available for Spring-based projects.
+
+* **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. A Spring module provides WebClient integration.
+
+* **How it fits the SDK**: This ensures all applications can talk to MCP servers out of the box, while allowing richer integration in Spring and other environments.
+
+#### Server Transport in the SDK
+
+* **SDK Choice**: Jakarta Servlet implementation in core, with optional Spring WebFlux and Spring WebMVC providers
+
+* **Why**: Servlet is the most widely deployed Java server API. WebFlux and WebMVC cover a significant part of the Spring community. Together these provide reach across blocking and non-blocking models.
+
+* **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring modules extend support for WebFlux and WebMVC.
+
+* **How it fits the SDK**: This allows developers to expose MCP servers in the most common Java environments today, while enabling other transport implementations such as Netty, Vert.x, or Helidon.
+
+#### Authorization in the SDK
+
+* **SDK Choice**: Pluggable authorization hooks for MCP servers; no built-in implementation
+
+* **Why**: MCP servers must restrict access to authenticated and authorized clients. Authorization needs differ across environments such as Spring Security, MicroProfile JWT, or custom solutions. Providing hooks avoids lock-in and leverages proven libraries.
+
+* **How we expose it**: Authorization is integrated into the server transport layer. The SDK does not include its own authorization system.
+
+* **How it fits the SDK**: This keeps server-side security ecosystem-neutral, while ensuring applications can plug in their preferred authorization strategy.
+
+### Project Structure of the SDK
+
+The SDK is organized into modules to separate concerns and allow adopters to bring in only what they need:
+* `mcp-bom` – Dependency versions
+* `mcp-core` – Reference implementation (STDIO, JDK HttpClient, Servlet)
+* `mcp-json` – JSON abstraction
+* `mcp-jackson2` – Jackson implementation of JSON binding
+* `mcp` – Convenience bundle (core + Jackson)
+* `mcp-test` – Shared testing utilities
+* `mcp-spring` – Spring integrations (WebClient, WebFlux, WebMVC)
+
+For example, a minimal adopter may depend only on `mcp` (core + Jackson), while a Spring-based application can use `mcp-spring` for deeper framework integration.
+
+### Future Directions
+
+The SDK is designed to evolve with the Java ecosystem. Areas we are actively watching include:
+Concurrency in the JDK – Virtual Threads and Structured Concurrency may simplify the synchronous API story
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).

From 95323b33713d6c5316ced618de2baf31771cbc2f Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Fri, 3 Oct 2025 10:56:50 +0200
Subject: [PATCH 090/125] Update theREADME team section

Signed-off-by: Christian Tzolov 
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 4ac7e8d5b..7bda15006 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,7 @@ Please follow the [Contributing Guidelines](CONTRIBUTING.md).
 
 - Christian Tzolov
 - Dariusz Jędrzejczyk
+- Daniel Garnier-Moiroux
 
 ## Links
 

From 83fc4f79de6f30a18de74dce67f231472029e768 Mon Sep 17 00:00:00 2001
From: Sergio del Amo 
Date: Mon, 6 Oct 2025 21:55:23 +0200
Subject: [PATCH 091/125] define explicitely that values should always be
 included in code completions (#601)

* define explicitely that values should always be included

* spring  apply
---
 .../modelcontextprotocol/spec/McpSchema.java  |  1 +
 .../CompleteCompletionSerializationTest.java  | 28 +++++++++++++++++++
 2 files changed, 29 insertions(+)
 create mode 100644 mcp-core/src/test/java/io/modelcontextprotocol/spec/CompleteCompletionSerializationTest.java

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 12835a57a..e37b4df60 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -2501,6 +2501,7 @@ public CompleteResult(CompleteCompletion completion) {
 		 * @param hasMore Indicates whether there are additional completion options beyond
 		 * those provided in the current response, even if the exact total is unknown
 		 */
+		@JsonInclude(JsonInclude.Include.ALWAYS)
 		public record CompleteCompletion( // @formatter:off
 				@JsonProperty("values") List values,
 				@JsonProperty("total") Integer total,
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/CompleteCompletionSerializationTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/CompleteCompletionSerializationTest.java
new file mode 100644
index 000000000..55f71fea4
--- /dev/null
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/CompleteCompletionSerializationTest.java
@@ -0,0 +1,28 @@
+package io.modelcontextprotocol.spec;
+
+import io.modelcontextprotocol.json.McpJsonMapper;
+import org.junit.jupiter.api.Test;
+import java.io.IOException;
+import java.util.Collections;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class CompleteCompletionSerializationTest {
+
+	@Test
+	void codeCompletionSerialization() throws IOException {
+		McpJsonMapper jsonMapper = McpJsonMapper.getDefault();
+		McpSchema.CompleteResult.CompleteCompletion codeComplete = new McpSchema.CompleteResult.CompleteCompletion(
+				Collections.emptyList(), 0, false);
+		String json = jsonMapper.writeValueAsString(codeComplete);
+		String expected = """
+				{"values":[],"total":0,"hasMore":false}""";
+		assertEquals(expected, json, json);
+
+		McpSchema.CompleteResult completeResult = new McpSchema.CompleteResult(codeComplete);
+		json = jsonMapper.writeValueAsString(completeResult);
+		expected = """
+				{"completion":{"values":[],"total":0,"hasMore":false}}""";
+		assertEquals(expected, json, json);
+	}
+
+}

From 94a8b53d8892b378705b8f6a37d2b1bbdb257916 Mon Sep 17 00:00:00 2001
From: Sergio del Amo 
Date: Mon, 6 Oct 2025 23:00:54 +0200
Subject: [PATCH 092/125] fix remove name when using deduction (#600)

This pull-request removes the name member from the @JsonSubTypes.Type annotations when using JsonTypeInfo.Id.DEDUCTION.

With DEDUCTION, Jackson ignores the name entirely because it's inferring the type from the structure.
---
 .../src/main/java/io/modelcontextprotocol/spec/McpSchema.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index e37b4df60..ead09d353 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -1064,8 +1064,8 @@ public UnsubscribeRequest(String uri) {
 	 * The contents of a specific resource or sub-resource.
 	 */
 	@JsonTypeInfo(use = JsonTypeInfo.Id.DEDUCTION)
-	@JsonSubTypes({ @JsonSubTypes.Type(value = TextResourceContents.class, name = "text"),
-			@JsonSubTypes.Type(value = BlobResourceContents.class, name = "blob") })
+	@JsonSubTypes({ @JsonSubTypes.Type(value = TextResourceContents.class),
+			@JsonSubTypes.Type(value = BlobResourceContents.class) })
 	public sealed interface ResourceContents extends Meta permits TextResourceContents, BlobResourceContents {
 
 		/**

From a63d32a5ea8aaf9812368476c71048fd395e0148 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Mon, 6 Oct 2025 23:04:42 +0200
Subject: [PATCH 093/125] refactor: change int to Integer for optional numeric
 fields (#604)

Convert primitive int types to Integer wrapper class for:
- JSONRPCError.code
- CreateMessageRequest.maxTokens (including constructor and builder)

This allows these fields to be nullable, properly representing
optional parameters in the MCP protocol schema.

Signed-off-by: Christian Tzolov 
---
 .../main/java/io/modelcontextprotocol/spec/McpSchema.java | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index ead09d353..e43469903 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -306,7 +306,7 @@ public record JSONRPCResponse( // @formatter:off
 		@JsonInclude(JsonInclude.Include.NON_ABSENT)
 		@JsonIgnoreProperties(ignoreUnknown = true)
 		public record JSONRPCError( // @formatter:off
-			@JsonProperty("code") int code,
+			@JsonProperty("code") Integer code,
 			@JsonProperty("message") String message,
 			@JsonProperty("data") Object data) { // @formatter:on
 		}
@@ -1822,14 +1822,14 @@ public record CreateMessageRequest( // @formatter:off
 		@JsonProperty("systemPrompt") String systemPrompt,
 		@JsonProperty("includeContext") ContextInclusionStrategy includeContext,
 		@JsonProperty("temperature") Double temperature,
-		@JsonProperty("maxTokens") int maxTokens,
+		@JsonProperty("maxTokens") Integer maxTokens,
 		@JsonProperty("stopSequences") List stopSequences,
 		@JsonProperty("metadata") Map metadata,
 		@JsonProperty("_meta") Map meta) implements Request { // @formatter:on
 
 		// backwards compatibility constructor
 		public CreateMessageRequest(List messages, ModelPreferences modelPreferences,
-				String systemPrompt, ContextInclusionStrategy includeContext, Double temperature, int maxTokens,
+				String systemPrompt, ContextInclusionStrategy includeContext, Double temperature, Integer maxTokens,
 				List stopSequences, Map metadata) {
 			this(messages, modelPreferences, systemPrompt, includeContext, temperature, maxTokens, stopSequences,
 					metadata, null);
@@ -1859,7 +1859,7 @@ public static class Builder {
 
 			private Double temperature;
 
-			private int maxTokens;
+			private Integer maxTokens;
 
 			private List stopSequences;
 

From 19a8c00a475d38c6104887d9df1ab503b4a51839 Mon Sep 17 00:00:00 2001
From: Sheegan Sri G M 
Date: Sat, 4 Oct 2025 09:42:58 +0530
Subject: [PATCH 094/125] fix: improve URI template matching to properly escape
 special characters (#599)

- Enhanced DefaultMcpUriTemplateManager to use Pattern.quote() for escaping special regex characters like '?'
- Replaced simple string replacement regex generation with robust pattern building
- Added test case to verify URI matching with query parameters (e.g., "file://name/search?={search}")
- Fixed typo: renamed DeafaultMcpUriTemplateManagerFactory to DefaultMcpUriTemplateManagerFactory
- Updated all references across server classes and tests

Signed-off-by: Christian Tzolov 
---
 .../server/McpAsyncServer.java                |  4 +--
 .../server/McpServer.java                     | 10 +++----
 .../server/McpStatelessAsyncServer.java       |  4 +--
 .../util/DefaultMcpUriTemplateManager.java    | 26 ++++++++++++++++---
 ... DefaultMcpUriTemplateManagerFactory.java} |  2 +-
 .../McpUriTemplateManagerTests.java           | 13 ++++++++--
 6 files changed, 43 insertions(+), 16 deletions(-)
 rename mcp-core/src/main/java/io/modelcontextprotocol/util/{DeafaultMcpUriTemplateManagerFactory.java => DefaultMcpUriTemplateManagerFactory.java} (86%)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index dcba3af1f..ac4b36990 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -36,7 +36,7 @@
 import io.modelcontextprotocol.spec.McpServerTransportProviderBase;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
-import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.DefaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.Utils;
 import org.slf4j.Logger;
@@ -120,7 +120,7 @@ public class McpAsyncServer {
 
 	private List protocolVersions;
 
-	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
 
 	/**
 	 * Create a new McpAsyncServer with the given transport provider and capabilities.
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
index 8e3ebf9e8..ecfb74b6a 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -25,7 +25,7 @@
 import io.modelcontextprotocol.spec.McpStatelessServerTransport;
 import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
 import io.modelcontextprotocol.util.Assert;
-import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.DefaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
 import reactor.core.publisher.Mono;
 
@@ -268,7 +268,7 @@ public McpAsyncServer build() {
 	 */
 	abstract class AsyncSpecification> {
 
-		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
 
 		McpJsonMapper jsonMapper;
 
@@ -865,7 +865,7 @@ public McpSyncServer build() {
 	 */
 	abstract class SyncSpecification> {
 
-		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
 
 		McpJsonMapper jsonMapper;
 
@@ -1407,7 +1407,7 @@ class StatelessAsyncSpecification {
 
 		private final McpStatelessServerTransport transport;
 
-		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
 
 		McpJsonMapper jsonMapper;
 
@@ -1870,7 +1870,7 @@ class StatelessSyncSpecification {
 
 		boolean immediateExecution = false;
 
-		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+		McpUriTemplateManagerFactory uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
 
 		McpJsonMapper jsonMapper;
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 823aca41d..997df7225 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -20,7 +20,7 @@
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpStatelessServerTransport;
 import io.modelcontextprotocol.util.Assert;
-import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.DefaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.Utils;
 import org.slf4j.Logger;
@@ -74,7 +74,7 @@ public class McpStatelessAsyncServer {
 
 	private List protocolVersions;
 
-	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+	private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
 
 	private final JsonSchemaValidator jsonSchemaValidator;
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
index ef51183a1..c3b922edf 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManager.java
@@ -141,12 +141,30 @@ public boolean matches(String uri) {
 			return uri.equals(this.uriTemplate);
 		}
 
-		// Convert the pattern to a regex
-		String regex = this.uriTemplate.replaceAll("\\{[^/]+?\\}", "([^/]+?)");
-		regex = regex.replace("/", "\\/");
+		// Convert the URI template into a robust regex pattern that escapes special
+		// characters like '?'.
+		StringBuilder patternBuilder = new StringBuilder("^");
+		Matcher variableMatcher = URI_VARIABLE_PATTERN.matcher(this.uriTemplate);
+		int lastEnd = 0;
+
+		while (variableMatcher.find()) {
+			// Append the literal part of the template, safely quoted
+			String textBefore = this.uriTemplate.substring(lastEnd, variableMatcher.start());
+			patternBuilder.append(Pattern.quote(textBefore));
+			// Append a capturing group for the variable itself
+			patternBuilder.append("([^/]+?)");
+			lastEnd = variableMatcher.end();
+		}
+
+		// Append any remaining literal text after the last variable
+		if (lastEnd < this.uriTemplate.length()) {
+			patternBuilder.append(Pattern.quote(this.uriTemplate.substring(lastEnd)));
+		}
+
+		patternBuilder.append("$");
 
 		// Check if the URI matches the regex
-		return Pattern.compile(regex).matcher(uri).matches();
+		return Pattern.compile(patternBuilder.toString()).matcher(uri).matches();
 	}
 
 	@Override
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java b/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManagerFactory.java
similarity index 86%
rename from mcp-core/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
rename to mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManagerFactory.java
index 44ea31690..fd1a3bd71 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/util/DeafaultMcpUriTemplateManagerFactory.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/util/DefaultMcpUriTemplateManagerFactory.java
@@ -7,7 +7,7 @@
 /**
  * @author Christian Tzolov
  */
-public class DeafaultMcpUriTemplateManagerFactory implements McpUriTemplateManagerFactory {
+public class DefaultMcpUriTemplateManagerFactory implements McpUriTemplateManagerFactory {
 
 	/**
 	 * Creates a new instance of {@link McpUriTemplateManager} with the specified URI
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java
index 6f041daa6..8f68f0d6e 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/McpUriTemplateManagerTests.java
@@ -12,7 +12,7 @@
 import java.util.List;
 import java.util.Map;
 
-import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.DefaultMcpUriTemplateManagerFactory;
 import io.modelcontextprotocol.util.McpUriTemplateManager;
 import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
 import org.junit.jupiter.api.BeforeEach;
@@ -29,7 +29,7 @@ public class McpUriTemplateManagerTests {
 
 	@BeforeEach
 	void setUp() {
-		this.uriTemplateFactory = new DeafaultMcpUriTemplateManagerFactory();
+		this.uriTemplateFactory = new DefaultMcpUriTemplateManagerFactory();
 	}
 
 	@Test
@@ -94,4 +94,13 @@ void shouldMatchUriAgainstTemplatePattern() {
 		assertFalse(uriTemplateManager.matches("/api/users/123/comments/456"));
 	}
 
+	@Test
+	void shouldMatchUriWithQueryParameters() {
+		String templateWithQuery = "file://name/search?={search}";
+		var uriTemplateManager = this.uriTemplateFactory.create(templateWithQuery);
+
+		assertTrue(uriTemplateManager.matches("file://name/search?=abcd"),
+				"Should correctly match a URI containing query parameters.");
+	}
+
 }

From 2ee58533d0d62f342db28a3749ce8e66c057236e Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Tue, 14 Oct 2025 09:30:59 +0200
Subject: [PATCH 095/125] fix: allow additional properties by default per JSON
 Schema spec (#617)

- Remove automatic additionalProperties: false injection (JSON Schema spec compliance)
- Support String input for structuredContent in validate() method
- Move tests to mcp-json-jackson2 module with proper dependencies
- Replace wildcard imports with explicit imports

Complies with JSON Schema Test Suite:
https://github.com/json-schema-org/JSON-Schema-Test-Suite/blob/15e4505/tests/draft2020-12/additionalProperties.json\#L112

Fixes #584

BREAKING CHANGE: Additional properties now allowed by default when not explicitly specified.

Signed-off-by: Christian Tzolov 
---
 .../spec/JSONRPCRequestMcpValidationTest.java |   5 +-
 .../spec/McpErrorTest.java                    |   3 +-
 .../spec/PromptReferenceEqualsTest.java       |   4 +-
 .../json/gson/GsonMcpJsonMapperTests.java     |   5 +-
 .../util/AssertTests.java                     |   4 +-
 mcp-json-jackson2/pom.xml                     |  26 ++++
 .../jackson/DefaultJsonSchemaValidator.java   |  23 +---
 .../DefaultJsonSchemaValidatorTests.java      | 113 +++++++++++++++++-
 8 files changed, 159 insertions(+), 24 deletions(-)
 rename {mcp-core/src/test/java/io/modelcontextprotocol/spec => mcp-json-jackson2/src/test/java/io/modelcontextprotocol/json}/DefaultJsonSchemaValidatorTests.java (84%)

diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
index d03a6926d..fbe17d464 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/JSONRPCRequestMcpValidationTest.java
@@ -5,7 +5,10 @@
 package io.modelcontextprotocol.spec;
 
 import org.junit.jupiter.api.Test;
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
  * Tests for MCP-specific validation of JSONRPCRequest ID requirements.
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java
index 84d650ab3..0978ffe0b 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpErrorTest.java
@@ -4,7 +4,8 @@
 
 import java.util.Map;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertEquals;
 
 class McpErrorTest {
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
index 382cda1ce..1d7be0b51 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/PromptReferenceEqualsTest.java
@@ -7,7 +7,9 @@
 import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import org.junit.jupiter.api.Test;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertEquals;
 
 /**
  * Test class to verify the equals method implementation for PromptReference.
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
index 4f1dffe1d..498194d17 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/json/gson/GsonMcpJsonMapperTests.java
@@ -8,7 +8,10 @@
 import java.util.List;
 import java.util.Map;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 
 class GsonMcpJsonMapperTests {
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/util/AssertTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/util/AssertTests.java
index 08555fef5..0038d4e1b 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/util/AssertTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/util/AssertTests.java
@@ -8,7 +8,9 @@
 
 import java.util.List;
 
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 
 class AssertTests {
 
diff --git a/mcp-json-jackson2/pom.xml b/mcp-json-jackson2/pom.xml
index 75569c78e..e53d5e57b 100644
--- a/mcp-json-jackson2/pom.xml
+++ b/mcp-json-jackson2/pom.xml
@@ -49,5 +49,31 @@
             json-schema-validator
             ${json-schema-validator.version}
         
+
+		
+			org.assertj
+			assertj-core
+			${assert4j.version}
+			test
+		
+		
+			org.junit.jupiter
+			junit-jupiter-api
+			${junit.version}
+			test
+		
+		
+			org.junit.jupiter
+			junit-jupiter-params
+			${junit.version}
+			test
+		
+		
+			org.mockito
+			mockito-core
+			${mockito.version}
+			test
+		
+
 	
 
diff --git a/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
index 7ec0419c8..15511c9c2 100644
--- a/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
+++ b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
@@ -7,18 +7,16 @@
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
-import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.node.ObjectNode;
 import com.networknt.schema.JsonSchema;
 import com.networknt.schema.JsonSchemaFactory;
 import com.networknt.schema.SpecVersion;
 import com.networknt.schema.ValidationMessage;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * Default implementation of the {@link JsonSchemaValidator} interface. This class
@@ -60,7 +58,9 @@ public ValidationResponse validate(Map schema, Object structured
 
 		try {
 
-			JsonNode jsonStructuredOutput = this.objectMapper.valueToTree(structuredContent);
+			JsonNode jsonStructuredOutput = (structuredContent instanceof String)
+					? this.objectMapper.readTree((String) structuredContent)
+					: this.objectMapper.valueToTree(structuredContent);
 
 			Set validationResult = this.getOrCreateJsonSchema(schema).validate(jsonStructuredOutput);
 
@@ -125,17 +125,6 @@ private JsonSchema createJsonSchema(Map schema) throws JsonProce
 			};
 		}
 
-		// Handle additionalProperties setting
-		if (schemaNode.isObject()) {
-			ObjectNode objectSchemaNode = (ObjectNode) schemaNode;
-			if (!objectSchemaNode.has("additionalProperties")) {
-				// Clone the node before modification to avoid mutating the original
-				objectSchemaNode = objectSchemaNode.deepCopy();
-				objectSchemaNode.put("additionalProperties", false);
-				schemaNode = objectSchemaNode;
-			}
-		}
-
 		return this.schemaFactory.getSchema(schemaNode);
 	}
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java b/mcp-json-jackson2/src/test/java/io/modelcontextprotocol/json/DefaultJsonSchemaValidatorTests.java
similarity index 84%
rename from mcp-core/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
rename to mcp-json-jackson2/src/test/java/io/modelcontextprotocol/json/DefaultJsonSchemaValidatorTests.java
index 76ca29684..7642f0480 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/DefaultJsonSchemaValidatorTests.java
+++ b/mcp-json-jackson2/src/test/java/io/modelcontextprotocol/json/DefaultJsonSchemaValidatorTests.java
@@ -2,7 +2,7 @@
  * Copyright 2024-2024 the original author or authors.
  */
 
-package io.modelcontextprotocol.spec;
+package io.modelcontextprotocol.json;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -13,6 +13,7 @@
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.when;
 
+import java.util.List;
 import java.util.Map;
 import java.util.stream.Stream;
 
@@ -64,6 +65,16 @@ private Map toMap(String json) {
 		}
 	}
 
+	private List> toListMap(String json) {
+		try {
+			return objectMapper.readValue(json, new TypeReference>>() {
+			});
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to parse JSON: " + json, e);
+		}
+	}
+
 	@Test
 	void testDefaultConstructor() {
 		DefaultJsonSchemaValidator defaultValidator = new DefaultJsonSchemaValidator();
@@ -198,6 +209,74 @@ void testValidateWithValidArraySchema() {
 		assertNull(response.errorMessage());
 	}
 
+	@Test
+	void testValidateWithValidArraySchemaTopLevelArray() {
+		String schemaJson = """
+				{
+					"$schema" : "https://json-schema.org/draft/2020-12/schema",
+					"type" : "array",
+					"items" : {
+						"type" : "object",
+						"properties" : {
+						"city" : {
+							"type" : "string"
+						},
+						"summary" : {
+							"type" : "string"
+						},
+						"temperatureC" : {
+							"type" : "number",
+							"format" : "float"
+						}
+						},
+						"required" : [ "city", "summary", "temperatureC" ]
+					},
+					"additionalProperties" : false
+				}
+					""";
+
+		String contentJson = """
+				[
+					{
+						"city": "London",
+						"summary": "Generally mild with frequent rainfall. Winters are cool and damp, summers are warm but rarely hot. Cloudy conditions are common throughout the year.",
+						"temperatureC": 11.3
+					},
+					{
+						"city": "New York",
+						"summary": "Four distinct seasons with hot and humid summers, cold winters with snow, and mild springs and autumns. Precipitation is fairly evenly distributed throughout the year.",
+						"temperatureC": 12.8
+					},
+					{
+						"city": "San Francisco",
+						"summary": "Mild year-round with a distinctive Mediterranean climate. Famous for summer fog, mild winters, and little temperature variation throughout the year. Very little rainfall in summer months.",
+						"temperatureC": 14.6
+					},
+					{
+						"city": "Tokyo",
+						"summary": "Humid subtropical climate with hot, wet summers and mild winters. Experiences a rainy season in early summer and occasional typhoons in late summer to early autumn.",
+						"temperatureC": 15.4
+					}
+				]
+				""";
+
+		Map schema = toMap(schemaJson);
+
+		// Validate as JSON string
+		ValidationResponse response = validator.validate(schema, contentJson);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+
+		List> structuredContent = toListMap(contentJson);
+
+		// Validate as List>
+		response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
 	@Test
 	void testValidateWithInvalidTypeSchema() {
 		String schemaJson = """
@@ -266,7 +345,8 @@ void testValidateWithAdditionalPropertiesNotAllowed() {
 					"properties": {
 						"name": {"type": "string"}
 					},
-					"required": ["name"]
+					"required": ["name"],
+					"additionalProperties": false
 				}
 				""";
 
@@ -316,6 +396,35 @@ void testValidateWithAdditionalPropertiesExplicitlyAllowed() {
 		assertNull(response.errorMessage());
 	}
 
+	@Test
+	void testValidateWithDefaultAdditionalProperties() {
+		String schemaJson = """
+				{
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"}
+					},
+					"required": ["name"],
+					"additionalProperties": true
+				}
+				""";
+
+		String contentJson = """
+				{
+					"name": "John Doe",
+					"extraField": "should be allowed"
+				}
+				""";
+
+		Map schema = toMap(schemaJson);
+		Map structuredContent = toMap(contentJson);
+
+		ValidationResponse response = validator.validate(schema, structuredContent);
+
+		assertTrue(response.valid());
+		assertNull(response.errorMessage());
+	}
+
 	@Test
 	void testValidateWithAdditionalPropertiesExplicitlyDisallowed() {
 		String schemaJson = """

From 9bbfbe573abb5920c731b9b3fbdd0d86b2cb9f87 Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Tue, 28 Oct 2025 14:26:21 +0100
Subject: [PATCH 096/125] Close McpTransportSession on transport close (#632)

* Client HTTP transports: use McpTransportSession interface instead of concrete types
* Streamable HTTP tranports: .closeGracefully closes the session

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../HttpClientStreamableHttpTransport.java    | 17 +++-
 .../spec/ClosedMcpTransportSession.java       | 58 ++++++++++++++
 .../McpTransportSessionClosedException.java   | 23 ++++++
 ...AbstractMcpAsyncClientResiliencyTests.java |  9 ++-
 ...HttpClientStreamableHttpTransportTest.java | 35 +++++++++
 .../WebClientStreamableHttpTransport.java     | 17 +++-
 .../WebClientStreamableHttpTransportTest.java | 77 +++++++++++++++++++
 ...AbstractMcpAsyncClientResiliencyTests.java |  9 ++-
 8 files changed, 229 insertions(+), 16 deletions(-)
 create mode 100644 mcp-core/src/main/java/io/modelcontextprotocol/spec/ClosedMcpTransportSession.java
 create mode 100644 mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionClosedException.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java

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 f4505c898..cd8fa171f 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
@@ -29,6 +29,7 @@
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.spec.ClosedMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
 import io.modelcontextprotocol.spec.HttpHeaders;
@@ -118,7 +119,7 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private final McpAsyncHttpClientRequestCustomizer httpRequestCustomizer;
 
-	private final AtomicReference activeSession = new AtomicReference<>();
+	private final AtomicReference> activeSession = new AtomicReference<>();
 
 	private final AtomicReference, Mono>> handler = new AtomicReference<>();
 
@@ -163,12 +164,20 @@ public Mono connect(Function, Mono createTransportSession() {
 		Function> onClose = sessionId -> sessionId == null ? Mono.empty()
 				: createDelete(sessionId);
 		return new DefaultMcpTransportSession(onClose);
 	}
 
+	private McpTransportSession createClosedSession(McpTransportSession existingSession) {
+		var existingSessionId = Optional.ofNullable(existingSession)
+			.filter(session -> !(session instanceof ClosedMcpTransportSession))
+			.flatMap(McpTransportSession::sessionId)
+			.orElse(null);
+		return new ClosedMcpTransportSession<>(existingSessionId);
+	}
+
 	private Publisher createDelete(String sessionId) {
 
 		var uri = Utils.resolveUri(this.baseUri, this.endpoint);
@@ -210,9 +219,9 @@ private void handleException(Throwable t) {
 	public Mono closeGracefully() {
 		return Mono.defer(() -> {
 			logger.debug("Graceful close triggered");
-			DefaultMcpTransportSession currentSession = this.activeSession.getAndSet(createTransportSession());
+			McpTransportSession currentSession = this.activeSession.getAndUpdate(this::createClosedSession);
 			if (currentSession != null) {
-				return currentSession.closeGracefully();
+				return Mono.from(currentSession.closeGracefully());
 			}
 			return Mono.empty();
 		});
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/ClosedMcpTransportSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/ClosedMcpTransportSession.java
new file mode 100644
index 000000000..b18364abb
--- /dev/null
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/ClosedMcpTransportSession.java
@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+package io.modelcontextprotocol.spec;
+
+import java.util.Optional;
+
+import org.reactivestreams.Publisher;
+import reactor.core.publisher.Mono;
+import reactor.util.annotation.Nullable;
+
+/**
+ * Represents a closed MCP session, which may not be reused. All calls will throw a
+ * {@link McpTransportSessionClosedException}.
+ *
+ * @param  the resource representing the connection that the transport
+ * manages.
+ * @author Daniel Garnier-Moiroux
+ */
+public class ClosedMcpTransportSession implements McpTransportSession {
+
+	private final String sessionId;
+
+	public ClosedMcpTransportSession(@Nullable String sessionId) {
+		this.sessionId = sessionId;
+	}
+
+	@Override
+	public Optional sessionId() {
+		throw new McpTransportSessionClosedException(sessionId);
+	}
+
+	@Override
+	public boolean markInitialized(String sessionId) {
+		throw new McpTransportSessionClosedException(sessionId);
+	}
+
+	@Override
+	public void addConnection(CONNECTION connection) {
+		throw new McpTransportSessionClosedException(sessionId);
+	}
+
+	@Override
+	public void removeConnection(CONNECTION connection) {
+		throw new McpTransportSessionClosedException(sessionId);
+	}
+
+	@Override
+	public void close() {
+
+	}
+
+	@Override
+	public Publisher closeGracefully() {
+		return Mono.empty();
+	}
+
+}
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionClosedException.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionClosedException.java
new file mode 100644
index 000000000..60e2850b9
--- /dev/null
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSessionClosedException.java
@@ -0,0 +1,23 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.spec;
+
+import reactor.util.annotation.Nullable;
+
+/**
+ * Exception thrown when trying to use an {@link McpTransportSession} that has been
+ * closed.
+ *
+ * @see ClosedMcpTransportSession
+ * @author Daniel Garnier-Moiroux
+ */
+public class McpTransportSessionClosedException extends RuntimeException {
+
+	public McpTransportSessionClosedException(@Nullable String sessionId) {
+		super(sessionId != null ? "MCP session with ID %s has been closed".formatted(sessionId)
+				: "MCP session has been closed");
+	}
+
+}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index 3dbd413af..183b8a365 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -10,7 +10,7 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpTransport;
-import org.junit.jupiter.api.Disabled;
+import io.modelcontextprotocol.spec.McpTransportSessionClosedException;
 import org.junit.jupiter.api.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -222,9 +222,10 @@ void testSessionClose() {
 			// In case of Streamable HTTP this call should issue a HTTP DELETE request
 			// invalidating the session
 			StepVerifier.create(mcpAsyncClient.closeGracefully()).expectComplete().verify();
-			// The next use should immediately re-initialize with no issue and send the
-			// request without any broken connections.
-			StepVerifier.create(mcpAsyncClient.ping()).expectNextCount(1).verifyComplete();
+			// The next tries to use the closed session and fails
+			StepVerifier.create(mcpAsyncClient.ping())
+				.expectErrorMatches(err -> err.getCause() instanceof McpTransportSessionClosedException)
+				.verify();
 		});
 	}
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index 0a09766d1..a1feb1f0e 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -125,4 +125,39 @@ void testAsyncRequestCustomizer() throws URISyntaxException {
 		});
 	}
 
+	@Test
+	void testCloseUninitialized() {
+		var transport = HttpClientStreamableHttpTransport.builder(host).build();
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+
+		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
+				McpSchema.ClientCapabilities.builder().roots(true).build(),
+				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
+				"test-id", initializeRequest);
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMessage("MCP session has been closed")
+			.verify();
+	}
+
+	@Test
+	void testCloseInitialized() {
+		var transport = HttpClientStreamableHttpTransport.builder(host).build();
+
+		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
+				McpSchema.ClientCapabilities.builder().roots(true).build(),
+				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
+				"test-id", initializeRequest);
+
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMatches(err -> err.getMessage().matches("MCP session with ID [a-zA-Z0-9-]* has been closed"))
+			.verify();
+	}
+
 }
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index f6ce9b4d3..5ec272961 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -25,6 +25,7 @@
 import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.json.McpJsonMapper;
 
+import io.modelcontextprotocol.spec.ClosedMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
 import io.modelcontextprotocol.spec.HttpHeaders;
@@ -98,7 +99,7 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 
 	private final boolean resumableStreams;
 
-	private final AtomicReference activeSession = new AtomicReference<>();
+	private final AtomicReference> activeSession = new AtomicReference<>();
 
 	private final AtomicReference, Mono>> handler = new AtomicReference<>();
 
@@ -143,7 +144,7 @@ public Mono connect(Function, Mono createTransportSession() {
 		Function> onClose = sessionId -> sessionId == null ? Mono.empty()
 				: webClient.delete()
 					.uri(this.endpoint)
@@ -159,6 +160,14 @@ private DefaultMcpTransportSession createTransportSession() {
 		return new DefaultMcpTransportSession(onClose);
 	}
 
+	private McpTransportSession createClosedSession(McpTransportSession existingSession) {
+		var existingSessionId = Optional.ofNullable(existingSession)
+			.filter(session -> !(session instanceof ClosedMcpTransportSession))
+			.flatMap(McpTransportSession::sessionId)
+			.orElse(null);
+		return new ClosedMcpTransportSession<>(existingSessionId);
+	}
+
 	@Override
 	public void setExceptionHandler(Consumer handler) {
 		logger.debug("Exception handler registered");
@@ -182,9 +191,9 @@ private void handleException(Throwable t) {
 	public Mono closeGracefully() {
 		return Mono.defer(() -> {
 			logger.debug("Graceful close triggered");
-			DefaultMcpTransportSession currentSession = this.activeSession.getAndSet(createTransportSession());
+			McpTransportSession currentSession = this.activeSession.getAndUpdate(this::createClosedSession);
 			if (currentSession != null) {
-				return currentSession.closeGracefully();
+				return Mono.from(currentSession.closeGracefully());
 			}
 			return Mono.empty();
 		});
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
new file mode 100644
index 000000000..27a39387b
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
@@ -0,0 +1,77 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ */
+package io.modelcontextprotocol.client.transport;
+
+import io.modelcontextprotocol.spec.McpSchema;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.testcontainers.containers.GenericContainer;
+import org.testcontainers.containers.wait.strategy.Wait;
+import reactor.test.StepVerifier;
+
+import org.springframework.web.reactive.function.client.WebClient;
+
+class WebClientStreamableHttpTransportTest {
+
+	static String host = "http://localhost:3001";
+
+	static WebClient.Builder builder;
+
+	@SuppressWarnings("resource")
+	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
+		.withCommand("node dist/index.js streamableHttp")
+		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
+		.withExposedPorts(3001)
+		.waitingFor(Wait.forHttp("/").forStatusCode(404));
+
+	@BeforeAll
+	static void startContainer() {
+		container.start();
+		int port = container.getMappedPort(3001);
+		host = "http://" + container.getHost() + ":" + port;
+		builder = WebClient.builder().baseUrl(host);
+	}
+
+	@AfterAll
+	static void stopContainer() {
+		container.stop();
+	}
+
+	@Test
+	void testCloseUninitialized() {
+		var transport = WebClientStreamableHttpTransport.builder(builder).build();
+
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+
+		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
+				McpSchema.ClientCapabilities.builder().roots(true).build(),
+				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
+				"test-id", initializeRequest);
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMessage("MCP session has been closed")
+			.verify();
+	}
+
+	@Test
+	void testCloseInitialized() {
+		var transport = WebClientStreamableHttpTransport.builder(builder).build();
+
+		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
+				McpSchema.ClientCapabilities.builder().roots(true).build(),
+				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
+				"test-id", initializeRequest);
+
+		StepVerifier.create(transport.sendMessage(testMessage)).verifyComplete();
+		StepVerifier.create(transport.closeGracefully()).verifyComplete();
+
+		StepVerifier.create(transport.sendMessage(testMessage))
+			.expectErrorMatches(err -> err.getMessage().matches("MCP session with ID [a-zA-Z0-9-]* has been closed"))
+			.verify();
+	}
+
+}
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index d1f316094..d0b1c46a2 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -10,7 +10,7 @@
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpTransport;
-import org.junit.jupiter.api.Disabled;
+import io.modelcontextprotocol.spec.McpTransportSessionClosedException;
 import org.junit.jupiter.api.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -221,9 +221,10 @@ void testSessionClose() {
 			// In case of Streamable HTTP this call should issue a HTTP DELETE request
 			// invalidating the session
 			StepVerifier.create(mcpAsyncClient.closeGracefully()).expectComplete().verify();
-			// The next use should immediately re-initialize with no issue and send the
-			// request without any broken connections.
-			StepVerifier.create(mcpAsyncClient.ping()).expectNextCount(1).verifyComplete();
+			// The next tries to use the closed session and fails
+			StepVerifier.create(mcpAsyncClient.ping())
+				.expectErrorMatches(err -> err.getCause() instanceof McpTransportSessionClosedException)
+				.verify();
 		});
 	}
 

From e91fe7fbc5a4981bf9395dfbc1a112a118830f79 Mon Sep 17 00:00:00 2001
From: lance 
Date: Thu, 30 Oct 2025 18:59:34 +0800
Subject: [PATCH 097/125] Fix: McpAsyncClient#listTools prevent infinite
 recursion (#631)

* Fix: prevent infinite recursion in listTools() when nextCursor is empty string

Signed-off-by: lance 
---
 .../client/McpAsyncClient.java                | 16 ++--
 .../client/McpAsyncClientTests.java           | 96 ++++++++++++++++---
 2 files changed, 90 insertions(+), 22 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 53a05aec3..2d1f4b43c 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -402,6 +402,7 @@ public Mono closeGracefully() {
 	// --------------------------
 	// Initialization
 	// --------------------------
+
 	/**
 	 * The initialization phase should be the first interaction between client and server.
 	 * The client will ensure it happens in case it has not been explicitly called and in
@@ -448,6 +449,7 @@ public Mono ping() {
 	// --------------------------
 	// Roots
 	// --------------------------
+
 	/**
 	 * Adds a new root to the client's root list.
 	 * @param root The root to add.
@@ -625,13 +627,13 @@ private McpSchema.CallToolResult validateToolResult(String toolName, McpSchema.C
 	 * @return A Mono that emits the list of all tools result
 	 */
 	public Mono listTools() {
-		return this.listTools(McpSchema.FIRST_PAGE)
-			.expand(result -> (result.nextCursor() != null) ? this.listTools(result.nextCursor()) : Mono.empty())
-			.reduce(new McpSchema.ListToolsResult(new ArrayList<>(), null), (allToolsResult, result) -> {
-				allToolsResult.tools().addAll(result.tools());
-				return allToolsResult;
-			})
-			.map(result -> new McpSchema.ListToolsResult(Collections.unmodifiableList(result.tools()), null));
+		return this.listTools(McpSchema.FIRST_PAGE).expand(result -> {
+			String next = result.nextCursor();
+			return (next != null && !next.isEmpty()) ? this.listTools(next) : Mono.empty();
+		}).reduce(new McpSchema.ListToolsResult(new ArrayList<>(), null), (allToolsResult, result) -> {
+			allToolsResult.tools().addAll(result.tools());
+			return allToolsResult;
+		}).map(result -> new McpSchema.ListToolsResult(Collections.unmodifiableList(result.tools()), null));
 	}
 
 	/**
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
index 970d8f257..48bf1da5b 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java
@@ -4,24 +4,22 @@
 
 package io.modelcontextprotocol.client;
 
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
 import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.ProtocolVersions;
-
 import org.junit.jupiter.api.Test;
-
-import com.fasterxml.jackson.core.JsonProcessingException;
-
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
-import java.util.List;
-import java.util.Map;
-import java.util.Objects;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.function.Function;
-
 import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
@@ -40,8 +38,7 @@ class McpAsyncClientTests {
 
 	private static final String CONTEXT_KEY = "context.key";
 
-	private McpClientTransport createMockTransportForToolValidation(boolean hasOutputSchema, boolean invalidOutput)
-			throws JsonProcessingException {
+	private McpClientTransport createMockTransportForToolValidation(boolean hasOutputSchema, boolean invalidOutput) {
 
 		// Create tool with or without output schema
 		Map inputSchemaMap = Map.of("type", "object", "properties",
@@ -182,7 +179,7 @@ public java.lang.reflect.Type getType() {
 	}
 
 	@Test
-	void testCallToolWithOutputSchemaValidationSuccess() throws JsonProcessingException {
+	void testCallToolWithOutputSchemaValidationSuccess() {
 		McpClientTransport transport = createMockTransportForToolValidation(true, false);
 
 		McpAsyncClient client = McpClient.async(transport).enableCallToolSchemaCaching(true).build();
@@ -204,7 +201,7 @@ void testCallToolWithOutputSchemaValidationSuccess() throws JsonProcessingExcept
 	}
 
 	@Test
-	void testCallToolWithNoOutputSchemaSuccess() throws JsonProcessingException {
+	void testCallToolWithNoOutputSchemaSuccess() {
 		McpClientTransport transport = createMockTransportForToolValidation(false, false);
 
 		McpAsyncClient client = McpClient.async(transport).enableCallToolSchemaCaching(true).build();
@@ -226,7 +223,7 @@ void testCallToolWithNoOutputSchemaSuccess() throws JsonProcessingException {
 	}
 
 	@Test
-	void testCallToolWithOutputSchemaValidationFailure() throws JsonProcessingException {
+	void testCallToolWithOutputSchemaValidationFailure() {
 		McpClientTransport transport = createMockTransportForToolValidation(true, true);
 
 		McpAsyncClient client = McpClient.async(transport).enableCallToolSchemaCaching(true).build();
@@ -241,4 +238,73 @@ void testCallToolWithOutputSchemaValidationFailure() throws JsonProcessingExcept
 		StepVerifier.create(client.closeGracefully()).verifyComplete();
 	}
 
+	@Test
+	void testListToolsWithEmptyCursor() {
+		McpSchema.Tool addTool = McpSchema.Tool.builder().name("add").description("calculate add").build();
+		McpSchema.Tool subtractTool = McpSchema.Tool.builder()
+			.name("subtract")
+			.description("calculate subtract")
+			.build();
+		McpSchema.ListToolsResult mockToolsResult = new McpSchema.ListToolsResult(List.of(addTool, subtractTool), "");
+
+		McpClientTransport transport = new McpClientTransport() {
+			Function, Mono> handler;
+
+			@Override
+			public Mono connect(
+					Function, Mono> handler) {
+				return Mono.deferContextual(ctx -> {
+					this.handler = handler;
+					return Mono.empty();
+				});
+			}
+
+			@Override
+			public Mono closeGracefully() {
+				return Mono.empty();
+			}
+
+			@Override
+			public Mono sendMessage(McpSchema.JSONRPCMessage message) {
+				if (!(message instanceof McpSchema.JSONRPCRequest request)) {
+					return Mono.empty();
+				}
+
+				McpSchema.JSONRPCResponse response;
+				if (McpSchema.METHOD_INITIALIZE.equals(request.method())) {
+					response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), MOCK_INIT_RESULT,
+							null);
+				}
+				else if (McpSchema.METHOD_TOOLS_LIST.equals(request.method())) {
+					response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), mockToolsResult,
+							null);
+				}
+				else {
+					return Mono.empty();
+				}
+
+				return handler.apply(Mono.just(response)).then();
+			}
+
+			@Override
+			public  T unmarshalFrom(Object data, TypeRef typeRef) {
+				return JSON_MAPPER.convertValue(data, new TypeRef<>() {
+					@Override
+					public java.lang.reflect.Type getType() {
+						return typeRef.getType();
+					}
+				});
+			}
+		};
+
+		McpAsyncClient client = McpClient.async(transport).enableCallToolSchemaCaching(true).build();
+
+		Mono mono = client.listTools();
+		McpSchema.ListToolsResult toolsResult = mono.block();
+		assertThat(toolsResult).isNotNull();
+
+		Set names = toolsResult.tools().stream().map(McpSchema.Tool::name).collect(Collectors.toSet());
+		assertThat(names).containsExactlyInAnyOrder("subtract", "add");
+	}
+
 }

From 5c46626260be588829a514a7a02b30d8c7903eaa Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Thu, 30 Oct 2025 12:17:42 +0100
Subject: [PATCH 098/125] chore: standardize client/server implementation names
 and version (#642)

Unifies client/server implementation names under "Java SDK" branding
and updates all versions to 0.15.0.

Resolves: #638

Signed-off-by: Christian Tzolov 
---
 .../io/modelcontextprotocol/client/McpClient.java    |  4 ++--
 .../io/modelcontextprotocol/server/McpServer.java    |  3 +--
 ...StreamableHttpTransportEmptyJsonResponseTest.java |  4 ++--
 .../HttpClientStreamableHttpTransportTest.java       | 12 ++++++------
 .../WebClientStreamableHttpTransportTest.java        |  4 ++--
 5 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
index e39d43e27..421f2fc7f 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
@@ -167,7 +167,7 @@ class SyncSpec {
 
 		private ClientCapabilities capabilities;
 
-		private Implementation clientInfo = new Implementation("Java SDK MCP Client", "1.0.0");
+		private Implementation clientInfo = new Implementation("Java SDK MCP Client", "0.15.0");
 
 		private final Map roots = new HashMap<>();
 
@@ -507,7 +507,7 @@ class AsyncSpec {
 
 		private ClientCapabilities capabilities;
 
-		private Implementation clientInfo = new Implementation("Spring AI MCP Client", "0.3.1");
+		private Implementation clientInfo = new Implementation("Java SDK MCP Client", "0.15.0");
 
 		private final Map roots = new HashMap<>();
 
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
index ecfb74b6a..047462ae4 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -11,7 +11,6 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.function.BiConsumer;
 import java.util.function.BiFunction;
 
@@ -134,7 +133,7 @@
  */
 public interface McpServer {
 
-	McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("mcp-server", "1.0.0");
+	McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("Java SDK MCP Server", "0.15.0");
 
 	/**
 	 * Starts building a synchronous MCP server that provides blocking operations.
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
index 250c7aa50..81e642681 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportEmptyJsonResponseTest.java
@@ -78,7 +78,7 @@ void testNotificationInitialized() throws URISyntaxException {
 
 		var initializeRequest = new McpSchema.InitializeRequest(ProtocolVersions.MCP_2025_03_26,
 				McpSchema.ClientCapabilities.builder().roots(true).build(),
-				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+				new McpSchema.Implementation("MCP Client", "0.3.1"));
 		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 				"test-id", initializeRequest);
 
@@ -86,7 +86,7 @@ void testNotificationInitialized() throws URISyntaxException {
 
 		// Verify the customizer was called
 		verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-				"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+				"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"MCP Client\",\"version\":\"0.3.1\"}}}"),
 				any());
 
 	}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index a1feb1f0e..f9536b690 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -80,7 +80,7 @@ void testRequestCustomizer() throws URISyntaxException {
 			// Send test message
 			var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
 					McpSchema.ClientCapabilities.builder().roots(true).build(),
-					new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+					new McpSchema.Implementation("MCP Client", "0.3.1"));
 			var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 					"test-id", initializeRequest);
 
@@ -90,7 +90,7 @@ void testRequestCustomizer() throws URISyntaxException {
 
 			// Verify the customizer was called
 			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"MCP Client\",\"version\":\"0.3.1\"}}}"),
 					eq(context));
 		});
 	}
@@ -110,7 +110,7 @@ void testAsyncRequestCustomizer() throws URISyntaxException {
 			// Send test message
 			var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
 					McpSchema.ClientCapabilities.builder().roots(true).build(),
-					new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+					new McpSchema.Implementation("MCP Client", "0.3.1"));
 			var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 					"test-id", initializeRequest);
 
@@ -120,7 +120,7 @@ void testAsyncRequestCustomizer() throws URISyntaxException {
 
 			// Verify the customizer was called
 			verify(mockRequestCustomizer, atLeastOnce()).customize(any(), eq("POST"), eq(uri), eq(
-					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"Spring AI MCP Client\",\"version\":\"0.3.1\"}}}"),
+					"{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"id\":\"test-id\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{\"roots\":{\"listChanged\":true}},\"clientInfo\":{\"name\":\"MCP Client\",\"version\":\"0.3.1\"}}}"),
 					eq(context));
 		});
 	}
@@ -133,7 +133,7 @@ void testCloseUninitialized() {
 
 		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
 				McpSchema.ClientCapabilities.builder().roots(true).build(),
-				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+				new McpSchema.Implementation("MCP Client", "0.3.1"));
 		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 				"test-id", initializeRequest);
 
@@ -148,7 +148,7 @@ void testCloseInitialized() {
 
 		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
 				McpSchema.ClientCapabilities.builder().roots(true).build(),
-				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+				new McpSchema.Implementation("MCP Client", "0.3.1"));
 		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 				"test-id", initializeRequest);
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
index 27a39387b..e2fcf91f7 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
@@ -47,7 +47,7 @@ void testCloseUninitialized() {
 
 		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
 				McpSchema.ClientCapabilities.builder().roots(true).build(),
-				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+				new McpSchema.Implementation("MCP Client", "0.3.1"));
 		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 				"test-id", initializeRequest);
 
@@ -62,7 +62,7 @@ void testCloseInitialized() {
 
 		var initializeRequest = new McpSchema.InitializeRequest(McpSchema.LATEST_PROTOCOL_VERSION,
 				McpSchema.ClientCapabilities.builder().roots(true).build(),
-				new McpSchema.Implementation("Spring AI MCP Client", "0.3.1"));
+				new McpSchema.Implementation("MCP Client", "0.3.1"));
 		var testMessage = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, McpSchema.METHOD_INITIALIZE,
 				"test-id", initializeRequest);
 

From 0980f08e94761496282e17d65934f6ab3a33c988 Mon Sep 17 00:00:00 2001
From: Dmitry Bedrin 
Date: Thu, 30 Oct 2025 16:26:25 +0100
Subject: [PATCH 099/125] Update dependencies minor versions to fix build on
 JDK 25 (#640)

---
 pom.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/pom.xml b/pom.xml
index f17b2b61b..2cd141863 100644
--- a/pom.xml
+++ b/pom.xml
@@ -59,16 +59,16 @@
 		17
 		
 
-		3.26.3
+		3.27.6
 		5.10.2
-		5.17.0
+		5.20.0
 		1.20.4
-		1.17.5
+		1.17.8
 		1.21.0
 
 		2.0.16
 		1.5.15
-		2.17.0
+		2.19.2
 		6.2.1
 
 		

From 14ff4a385dc8b953886a56966b675a0794b72638 Mon Sep 17 00:00:00 2001
From: Dmitry Bedrin 
Date: Thu, 30 Oct 2025 16:27:08 +0100
Subject: [PATCH 100/125] Support o.s.h.HttpHeaders from both 6.x and 7.x
 branches to enable migration to Spring 7 (#639)

---
 .../WebFluxStreamableServerTransportProvider.java         | 8 ++++----
 .../WebMvcStreamableServerTransportProvider.java          | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
index 144a3ce02..deebfc616 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
@@ -174,7 +174,7 @@ private Mono handleGet(ServerRequest request) {
 				return ServerResponse.badRequest().build();
 			}
 
-			if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+			if (request.headers().header(HttpHeaders.MCP_SESSION_ID).isEmpty()) {
 				return ServerResponse.badRequest().build(); // TODO: say we need a session
 															// id
 			}
@@ -187,7 +187,7 @@ private Mono handleGet(ServerRequest request) {
 				return ServerResponse.notFound().build();
 			}
 
-			if (request.headers().asHttpHeaders().containsKey(HttpHeaders.LAST_EVENT_ID)) {
+			if (!request.headers().header(HttpHeaders.LAST_EVENT_ID).isEmpty()) {
 				String lastId = request.headers().asHttpHeaders().getFirst(HttpHeaders.LAST_EVENT_ID);
 				return ServerResponse.ok()
 					.contentType(MediaType.TEXT_EVENT_STREAM)
@@ -258,7 +258,7 @@ private Mono handlePost(ServerRequest request) {
 							.bodyValue(initResult));
 				}
 
-				if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+				if (request.headers().header(HttpHeaders.MCP_SESSION_ID).isEmpty()) {
 					return ServerResponse.badRequest().bodyValue(new McpError("Session ID missing"));
 				}
 
@@ -313,7 +313,7 @@ private Mono handleDelete(ServerRequest request) {
 		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
 		return Mono.defer(() -> {
-			if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+			if (request.headers().header(HttpHeaders.MCP_SESSION_ID).isEmpty()) {
 				return ServerResponse.badRequest().build(); // TODO: say we need a session
 															// id
 			}
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
index d85046a67..f2a58d4d8 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java
@@ -240,7 +240,7 @@ private ServerResponse handleGet(ServerRequest request) {
 
 		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
-		if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+		if (request.headers().header(HttpHeaders.MCP_SESSION_ID).isEmpty()) {
 			return ServerResponse.badRequest().body("Session ID required in mcp-session-id header");
 		}
 
@@ -263,7 +263,7 @@ private ServerResponse handleGet(ServerRequest request) {
 						sessionId, sseBuilder);
 
 				// Check if this is a replay request
-				if (request.headers().asHttpHeaders().containsKey(HttpHeaders.LAST_EVENT_ID)) {
+				if (!request.headers().header(HttpHeaders.LAST_EVENT_ID).isEmpty()) {
 					String lastId = request.headers().asHttpHeaders().getFirst(HttpHeaders.LAST_EVENT_ID);
 
 					try {
@@ -354,7 +354,7 @@ private ServerResponse handlePost(ServerRequest request) {
 			}
 
 			// Handle other messages that require a session
-			if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+			if (request.headers().header(HttpHeaders.MCP_SESSION_ID).isEmpty()) {
 				return ServerResponse.badRequest().body(new McpError("Session ID missing"));
 			}
 
@@ -433,7 +433,7 @@ private ServerResponse handleDelete(ServerRequest request) {
 
 		McpTransportContext transportContext = this.contextExtractor.extract(request);
 
-		if (!request.headers().asHttpHeaders().containsKey(HttpHeaders.MCP_SESSION_ID)) {
+		if (request.headers().header(HttpHeaders.MCP_SESSION_ID).isEmpty()) {
 			return ServerResponse.badRequest().body("Session ID required in mcp-session-id header");
 		}
 

From 6e9af40bcbb2b5ee12748f7c5f20b0a7d479c5f8 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 30 Oct 2025 19:02:32 +0100
Subject: [PATCH 101/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       |  2 +-
 mcp-core/pom.xml                      |  6 +++---
 mcp-json-jackson2/pom.xml             |  4 ++--
 mcp-json/pom.xml                      |  2 +-
 mcp-spring/mcp-spring-webflux/pom.xml |  8 ++++----
 mcp-spring/mcp-spring-webmvc/pom.xml  | 10 +++++-----
 mcp-test/pom.xml                      |  4 ++--
 mcp/pom.xml                           |  6 +++---
 pom.xml                               |  2 +-
 9 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index 3c83afda3..fc08f3d67 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.15.0-SNAPSHOT
+        0.16.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-core/pom.xml b/mcp-core/pom.xml
index 5681385b6..6ac8c2aba 100644
--- a/mcp-core/pom.xml
+++ b/mcp-core/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.15.0-SNAPSHOT
+		0.16.0-SNAPSHOT
 	
 	mcp-core
 	jar
@@ -68,7 +68,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.15.0-SNAPSHOT
+            0.16.0-SNAPSHOT
         
 
 		
@@ -101,7 +101,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.15.0-SNAPSHOT
+            0.16.0-SNAPSHOT
             test
         
 
diff --git a/mcp-json-jackson2/pom.xml b/mcp-json-jackson2/pom.xml
index e53d5e57b..7e7000b97 100644
--- a/mcp-json-jackson2/pom.xml
+++ b/mcp-json-jackson2/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.15.0-SNAPSHOT
+		0.16.0-SNAPSHOT
 	
 	mcp-json-jackson2
 	jar
@@ -37,7 +37,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.15.0-SNAPSHOT
+            0.16.0-SNAPSHOT
         
         
             com.fasterxml.jackson.core
diff --git a/mcp-json/pom.xml b/mcp-json/pom.xml
index 790b056c6..c12801fd4 100644
--- a/mcp-json/pom.xml
+++ b/mcp-json/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.15.0-SNAPSHOT
+		0.16.0-SNAPSHOT
 	
 	mcp-json
 	jar
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 785ebd746..c9b85f51d 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.15.0-SNAPSHOT
+		0.16.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,19 +25,19 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.15.0-SNAPSHOT
+            0.16.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 3dc0e13f9..94b5c5881 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.15.0-SNAPSHOT
+		0.16.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,13 +25,13 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.15.0-SNAPSHOT
+            0.16.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 		
 
 		
@@ -43,14 +43,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 			test
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 27560e10e..7618779b6 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.15.0-SNAPSHOT
+		0.16.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 412f7dc6b..ce4fd7552 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.15.0-SNAPSHOT
+		0.16.0-SNAPSHOT
 	
 	mcp
 	jar
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-json-jackson2
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-core
-			0.15.0-SNAPSHOT
+			0.16.0-SNAPSHOT
 		
 	
 
diff --git a/pom.xml b/pom.xml
index 2cd141863..144a06c53 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.15.0-SNAPSHOT
+	0.16.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From 476f9db36fa8cd54c059e620a9d2877586043d50 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Fri, 7 Nov 2025 11:56:21 +0200
Subject: [PATCH 102/125] feat: enhance error handling with custom error code
 preservation (#653)

- Improve McpClientSession error handling to preserve custom error codes
and data from McpError instances.
- Add aggregated exception messages to error data field for better debugging.
- Include test coverage for various McpClientSession error scenarios.

Signed-off-by: Christian Tzolov 
---
 .../spec/McpClientSession.java                |  10 +-
 .../spec/McpClientSessionTests.java           | 189 ++++++++++++++----
 2 files changed, 160 insertions(+), 39 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
index bc3f53467..0ba7ab3b8 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java
@@ -166,9 +166,15 @@ private void handle(McpSchema.JSONRPCMessage message) {
 		else if (message instanceof McpSchema.JSONRPCRequest request) {
 			logger.debug("Received request: {}", request);
 			handleIncomingRequest(request).onErrorResume(error -> {
+
+				McpSchema.JSONRPCResponse.JSONRPCError jsonRpcError = (error instanceof McpError mcpError
+						&& mcpError.getJsonRpcError() != null) ? mcpError.getJsonRpcError()
+								// TODO: add error message through the data field
+								: new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
+										error.getMessage(), McpError.aggregateExceptionMessages(error));
+
 				var errorResponse = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null,
-						new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.INTERNAL_ERROR,
-								error.getMessage(), null));
+						jsonRpcError);
 				return Mono.just(errorResponse);
 			}).flatMap(this.transport::sendMessage).onErrorComplete(t -> {
 				logger.warn("Issue sending response to the client, ", t);
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
index 86912b4bf..3de06f503 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpClientSessionTests.java
@@ -6,11 +6,10 @@
 
 import java.time.Duration;
 import java.util.Map;
+import java.util.function.Function;
 
 import io.modelcontextprotocol.MockMcpClientTransport;
 import io.modelcontextprotocol.json.TypeRef;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -19,7 +18,6 @@
 import reactor.test.StepVerifier;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 /**
  * Test suite for {@link McpClientSession} that verifies its JSON-RPC message handling,
@@ -39,35 +37,6 @@ class McpClientSessionTests {
 
 	private static final String ECHO_METHOD = "echo";
 
-	private McpClientSession session;
-
-	private MockMcpClientTransport transport;
-
-	@BeforeEach
-	void setUp() {
-		transport = new MockMcpClientTransport();
-		session = new McpClientSession(TIMEOUT, transport, Map.of(),
-				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))));
-	}
-
-	@AfterEach
-	void tearDown() {
-		if (session != null) {
-			session.close();
-		}
-	}
-
-	@Test
-	void testConstructorWithInvalidArguments() {
-		assertThatThrownBy(() -> new McpClientSession(null, transport, Map.of(), Map.of()))
-			.isInstanceOf(IllegalArgumentException.class)
-			.hasMessageContaining("The requestTimeout can not be null");
-
-		assertThatThrownBy(() -> new McpClientSession(TIMEOUT, null, Map.of(), Map.of()))
-			.isInstanceOf(IllegalArgumentException.class)
-			.hasMessageContaining("transport can not be null");
-	}
-
 	TypeRef responseType = new TypeRef<>() {
 	};
 
@@ -76,6 +45,11 @@ void testSendRequest() {
 		String testParam = "test parameter";
 		String responseData = "test response";
 
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(),
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))),
+				Function.identity());
+
 		// Create a Mono that will emit the response after the request is sent
 		Mono responseMono = session.sendRequest(TEST_METHOD, testParam, responseType);
 		// Verify response handling
@@ -92,10 +66,17 @@ void testSendRequest() {
 			assertThat(request.params()).isEqualTo(testParam);
 			assertThat(response).isEqualTo(responseData);
 		}).verifyComplete();
+
+		session.close();
 	}
 
 	@Test
 	void testSendRequestWithError() {
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(),
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))),
+				Function.identity());
+
 		Mono responseMono = session.sendRequest(TEST_METHOD, "test", responseType);
 
 		// Verify error handling
@@ -107,20 +88,34 @@ void testSendRequestWithError() {
 			transport.simulateIncomingMessage(
 					new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), null, error));
 		}).expectError(McpError.class).verify();
+
+		session.close();
 	}
 
 	@Test
 	void testRequestTimeout() {
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(),
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))),
+				Function.identity());
+
 		Mono responseMono = session.sendRequest(TEST_METHOD, "test", responseType);
 
 		// Verify timeout
 		StepVerifier.create(responseMono)
 			.expectError(java.util.concurrent.TimeoutException.class)
 			.verify(TIMEOUT.plusSeconds(1));
+
+		session.close();
 	}
 
 	@Test
 	void testSendNotification() {
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(),
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))),
+				Function.identity());
+
 		Map params = Map.of("key", "value");
 		Mono notificationMono = session.sendNotification(TEST_NOTIFICATION, params);
 
@@ -132,6 +127,8 @@ void testSendNotification() {
 			assertThat(notification.method()).isEqualTo(TEST_NOTIFICATION);
 			assertThat(notification.params()).isEqualTo(params);
 		}).verifyComplete();
+
+		session.close();
 	}
 
 	@Test
@@ -139,8 +136,8 @@ void testRequestHandling() {
 		String echoMessage = "Hello MCP!";
 		Map> requestHandlers = Map.of(ECHO_METHOD,
 				params -> Mono.just(params));
-		transport = new MockMcpClientTransport();
-		session = new McpClientSession(TIMEOUT, transport, requestHandlers, Map.of());
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, requestHandlers, Map.of(), Function.identity());
 
 		// Simulate incoming request
 		McpSchema.JSONRPCRequest request = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, ECHO_METHOD,
@@ -153,15 +150,18 @@ void testRequestHandling() {
 		McpSchema.JSONRPCResponse response = (McpSchema.JSONRPCResponse) sentMessage;
 		assertThat(response.result()).isEqualTo(echoMessage);
 		assertThat(response.error()).isNull();
+
+		session.close();
 	}
 
 	@Test
 	void testNotificationHandling() {
 		Sinks.One receivedParams = Sinks.one();
 
-		transport = new MockMcpClientTransport();
-		session = new McpClientSession(TIMEOUT, transport, Map.of(),
-				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> receivedParams.tryEmitValue(params))));
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(),
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> receivedParams.tryEmitValue(params))),
+				Function.identity());
 
 		// Simulate incoming notification from the server
 		Map notificationParams = Map.of("status", "ready");
@@ -173,10 +173,18 @@ void testNotificationHandling() {
 
 		// Verify handler was called
 		assertThat(receivedParams.asMono().block(Duration.ofSeconds(1))).isEqualTo(notificationParams);
+
+		session.close();
 	}
 
 	@Test
 	void testUnknownMethodHandling() {
+
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(),
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))),
+				Function.identity());
+
 		// Simulate incoming request for unknown method
 		McpSchema.JSONRPCRequest request = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, "unknown.method",
 				"test-id", null);
@@ -188,10 +196,117 @@ void testUnknownMethodHandling() {
 		McpSchema.JSONRPCResponse response = (McpSchema.JSONRPCResponse) sentMessage;
 		assertThat(response.error()).isNotNull();
 		assertThat(response.error().code()).isEqualTo(McpSchema.ErrorCodes.METHOD_NOT_FOUND);
+
+		session.close();
+	}
+
+	@Test
+	void testRequestHandlerThrowsMcpErrorWithJsonRpcError() {
+		// Setup: Create a request handler that throws McpError with custom error code and
+		// data
+		String testMethod = "test.customError";
+		Map errorData = Map.of("customField", "customValue");
+		McpClientSession.RequestHandler failingHandler = params -> Mono
+			.error(McpError.builder(123).message("Custom error message").data(errorData).build());
+
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(testMethod, failingHandler), Map.of(),
+				Function.identity());
+
+		// Simulate incoming request that will trigger the error
+		McpSchema.JSONRPCRequest request = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, testMethod,
+				"test-id", null);
+		transport.simulateIncomingMessage(request);
+
+		// Verify: The response should contain the custom error from McpError
+		McpSchema.JSONRPCMessage sentMessage = transport.getLastSentMessage();
+		assertThat(sentMessage).isInstanceOf(McpSchema.JSONRPCResponse.class);
+		McpSchema.JSONRPCResponse response = (McpSchema.JSONRPCResponse) sentMessage;
+		assertThat(response.error()).isNotNull();
+		assertThat(response.error().code()).isEqualTo(123);
+		assertThat(response.error().message()).isEqualTo("Custom error message");
+		assertThat(response.error().data()).isEqualTo(errorData);
+
+		session.close();
+	}
+
+	@Test
+	void testRequestHandlerThrowsGenericException() {
+		// Setup: Create a request handler that throws a generic RuntimeException
+		String testMethod = "test.genericError";
+		RuntimeException exception = new RuntimeException("Something went wrong");
+		McpClientSession.RequestHandler failingHandler = params -> Mono.error(exception);
+
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(testMethod, failingHandler), Map.of(),
+				Function.identity());
+
+		// Simulate incoming request that will trigger the error
+		McpSchema.JSONRPCRequest request = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, testMethod,
+				"test-id", null);
+		transport.simulateIncomingMessage(request);
+
+		// Verify: The response should contain INTERNAL_ERROR with aggregated exception
+		// messages in data field
+		McpSchema.JSONRPCMessage sentMessage = transport.getLastSentMessage();
+		assertThat(sentMessage).isInstanceOf(McpSchema.JSONRPCResponse.class);
+		McpSchema.JSONRPCResponse response = (McpSchema.JSONRPCResponse) sentMessage;
+		assertThat(response.error()).isNotNull();
+		assertThat(response.error().code()).isEqualTo(McpSchema.ErrorCodes.INTERNAL_ERROR);
+		assertThat(response.error().message()).isEqualTo("Something went wrong");
+		// Verify data field contains aggregated exception messages
+		assertThat(response.error().data()).isNotNull();
+		assertThat(response.error().data().toString()).contains("RuntimeException");
+		assertThat(response.error().data().toString()).contains("Something went wrong");
+
+		session.close();
+	}
+
+	@Test
+	void testRequestHandlerThrowsExceptionWithCause() {
+		// Setup: Create a request handler that throws an exception with a cause chain
+		String testMethod = "test.chainedError";
+		RuntimeException rootCause = new IllegalArgumentException("Root cause message");
+		RuntimeException middleCause = new IllegalStateException("Middle cause message", rootCause);
+		RuntimeException topException = new RuntimeException("Top level message", middleCause);
+		McpClientSession.RequestHandler failingHandler = params -> Mono.error(topException);
+
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(testMethod, failingHandler), Map.of(),
+				Function.identity());
+
+		// Simulate incoming request that will trigger the error
+		McpSchema.JSONRPCRequest request = new McpSchema.JSONRPCRequest(McpSchema.JSONRPC_VERSION, testMethod,
+				"test-id", null);
+		transport.simulateIncomingMessage(request);
+
+		// Verify: The response should contain INTERNAL_ERROR with full exception chain
+		// in data field
+		McpSchema.JSONRPCMessage sentMessage = transport.getLastSentMessage();
+		assertThat(sentMessage).isInstanceOf(McpSchema.JSONRPCResponse.class);
+		McpSchema.JSONRPCResponse response = (McpSchema.JSONRPCResponse) sentMessage;
+		assertThat(response.error()).isNotNull();
+		assertThat(response.error().code()).isEqualTo(McpSchema.ErrorCodes.INTERNAL_ERROR);
+		assertThat(response.error().message()).isEqualTo("Top level message");
+		// Verify data field contains the full exception chain
+		String dataString = response.error().data().toString();
+		assertThat(dataString).contains("RuntimeException");
+		assertThat(dataString).contains("Top level message");
+		assertThat(dataString).contains("IllegalStateException");
+		assertThat(dataString).contains("Middle cause message");
+		assertThat(dataString).contains("IllegalArgumentException");
+		assertThat(dataString).contains("Root cause message");
+
+		session.close();
 	}
 
 	@Test
 	void testGracefulShutdown() {
+		var transport = new MockMcpClientTransport();
+		var session = new McpClientSession(TIMEOUT, transport, Map.of(),
+				Map.of(TEST_NOTIFICATION, params -> Mono.fromRunnable(() -> logger.info("Status update: {}", params))),
+				Function.identity());
+
 		StepVerifier.create(session.closeGracefully()).verifyComplete();
 	}
 

From ed85f7ee3ef778e15908140ada09fc9b3460112c Mon Sep 17 00:00:00 2001
From: Uladzislau Arlouski 
Date: Wed, 12 Nov 2025 16:21:09 +0300
Subject: [PATCH 103/125] Bump json-schema-validator from 1.5.7 to 2.0.0 (#660)

---
 .../jackson/DefaultJsonSchemaValidator.java   | 36 +++++++++----------
 pom.xml                                       |  2 +-
 2 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
index 15511c9c2..1ff28cb80 100644
--- a/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
+++ b/mcp-json-jackson2/src/main/java/io/modelcontextprotocol/json/schema/jackson/DefaultJsonSchemaValidator.java
@@ -3,17 +3,17 @@
  */
 package io.modelcontextprotocol.json.schema.jackson;
 
+import java.util.List;
 import java.util.Map;
-import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import com.networknt.schema.JsonSchema;
-import com.networknt.schema.JsonSchemaFactory;
-import com.networknt.schema.SpecVersion;
-import com.networknt.schema.ValidationMessage;
+import com.networknt.schema.Schema;
+import com.networknt.schema.SchemaRegistry;
+import com.networknt.schema.Error;
+import com.networknt.schema.dialect.Dialects;
 import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -31,10 +31,10 @@ public class DefaultJsonSchemaValidator implements JsonSchemaValidator {
 
 	private final ObjectMapper objectMapper;
 
-	private final JsonSchemaFactory schemaFactory;
+	private final SchemaRegistry schemaFactory;
 
 	// TODO: Implement a strategy to purge the cache (TTL, size limit, etc.)
-	private final ConcurrentHashMap schemaCache;
+	private final ConcurrentHashMap schemaCache;
 
 	public DefaultJsonSchemaValidator() {
 		this(new ObjectMapper());
@@ -42,7 +42,7 @@ public DefaultJsonSchemaValidator() {
 
 	public DefaultJsonSchemaValidator(ObjectMapper objectMapper) {
 		this.objectMapper = objectMapper;
-		this.schemaFactory = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012);
+		this.schemaFactory = SchemaRegistry.withDialect(Dialects.getDraft202012());
 		this.schemaCache = new ConcurrentHashMap<>();
 	}
 
@@ -62,7 +62,7 @@ public ValidationResponse validate(Map schema, Object structured
 					? this.objectMapper.readTree((String) structuredContent)
 					: this.objectMapper.valueToTree(structuredContent);
 
-			Set validationResult = this.getOrCreateJsonSchema(schema).validate(jsonStructuredOutput);
+			List validationResult = this.getOrCreateJsonSchema(schema).validate(jsonStructuredOutput);
 
 			// Check if validation passed
 			if (!validationResult.isEmpty()) {
@@ -85,36 +85,36 @@ public ValidationResponse validate(Map schema, Object structured
 	}
 
 	/**
-	 * Gets a cached JsonSchema or creates and caches a new one.
+	 * Gets a cached Schema or creates and caches a new one.
 	 * @param schema the schema map to convert
-	 * @return the compiled JsonSchema
+	 * @return the compiled Schema
 	 * @throws JsonProcessingException if schema processing fails
 	 */
-	private JsonSchema getOrCreateJsonSchema(Map schema) throws JsonProcessingException {
+	private Schema getOrCreateJsonSchema(Map schema) throws JsonProcessingException {
 		// Generate cache key based on schema content
 		String cacheKey = this.generateCacheKey(schema);
 
 		// Try to get from cache first
-		JsonSchema cachedSchema = this.schemaCache.get(cacheKey);
+		Schema cachedSchema = this.schemaCache.get(cacheKey);
 		if (cachedSchema != null) {
 			return cachedSchema;
 		}
 
 		// Create new schema if not in cache
-		JsonSchema newSchema = this.createJsonSchema(schema);
+		Schema newSchema = this.createJsonSchema(schema);
 
 		// Cache the schema
-		JsonSchema existingSchema = this.schemaCache.putIfAbsent(cacheKey, newSchema);
+		Schema existingSchema = this.schemaCache.putIfAbsent(cacheKey, newSchema);
 		return existingSchema != null ? existingSchema : newSchema;
 	}
 
 	/**
-	 * Creates a new JsonSchema from the given schema map.
+	 * Creates a new Schema from the given schema map.
 	 * @param schema the schema map
-	 * @return the compiled JsonSchema
+	 * @return the compiled Schema
 	 * @throws JsonProcessingException if schema processing fails
 	 */
-	private JsonSchema createJsonSchema(Map schema) throws JsonProcessingException {
+	private Schema createJsonSchema(Map schema) throws JsonProcessingException {
 		// Convert schema map directly to JsonNode (more efficient than string
 		// serialization)
 		JsonNode schemaNode = this.objectMapper.valueToTree(schema);
diff --git a/pom.xml b/pom.xml
index 144a06c53..1ff45596e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -96,7 +96,7 @@
 		4.2.0
 		7.1.0
 		4.1.0
-		1.5.7
+		2.0.0
 
 	
 

From afa00902a4d7c225e1ec3947aae5011fe70deeaa Mon Sep 17 00:00:00 2001
From: Michael Vorburger 
Date: Wed, 12 Nov 2025 14:21:57 +0100
Subject: [PATCH 104/125] fix: JSONRPCResponse JavaDoc (#657)

---
 .../main/java/io/modelcontextprotocol/spec/McpSchema.java   | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index e43469903..3f3f78df8 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -277,12 +277,12 @@ public record JSONRPCNotification( // @formatter:off
 	}
 
 	/**
-	 * A successful (non-error) response to a request.
+	 * A response to a request (successful, or error).
 	 *
 	 * @param jsonrpc The JSON-RPC version (must be "2.0")
 	 * @param id The request identifier that this response corresponds to
-	 * @param result The result of the successful request
-	 * @param error Error information if the request failed
+	 * @param result The result of the successful request; null if error
+	 * @param error Error information if the request failed; null if has result
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)

From 738525308d3d151d0af28cc560d0717e32856653 Mon Sep 17 00:00:00 2001
From: Viliam Sun 
Date: Wed, 12 Nov 2025 21:44:35 +0800
Subject: [PATCH 105/125] fix(docs): Remove broken @see link in
 resourceTemplates Javadoc (#614)

---
 .../main/java/io/modelcontextprotocol/server/McpServer.java   | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
index 047462ae4..87c84ba1b 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -598,7 +598,6 @@ public AsyncSpecification resources(McpServerFeatures.AsyncResourceSpecificat
 		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
-		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
 		public AsyncSpecification resourceTemplates(
 				List resourceTemplates) {
@@ -1195,7 +1194,6 @@ public SyncSpecification resources(McpServerFeatures.SyncResourceSpecificatio
 		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
-		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
 		public SyncSpecification resourceTemplates(
 				List resourceTemplates) {
@@ -1703,7 +1701,6 @@ public StatelessAsyncSpecification resources(
 		 * templates.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
-		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
 		public StatelessAsyncSpecification resourceTemplates(
 				List resourceTemplates) {
@@ -2166,7 +2163,6 @@ public StatelessSyncSpecification resources(
 		 * existing templates.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
-		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
 		public StatelessSyncSpecification resourceTemplates(
 				List resourceTemplatesSpec) {

From b74f6de9dcc5ac1c6bdc6d2dd29c97d875574fcd Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Wed, 12 Nov 2025 15:20:44 +0100
Subject: [PATCH 106/125] feat(schema): support Object type for progressToken
 (#663)

Change progressToken from String to Object throughout McpSchema
to allow both String and Number token types.
This makes it compliant with the MCP spec.

Resolves: #659

Signed-off-by: Christian Tzolov 
---
 .../io/modelcontextprotocol/spec/McpSchema.java    | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 3f3f78df8..342fc5347 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -167,9 +167,9 @@ public sealed interface Request extends Meta
 			permits InitializeRequest, CallToolRequest, CreateMessageRequest, ElicitRequest, CompleteRequest,
 			GetPromptRequest, ReadResourceRequest, SubscribeRequest, UnsubscribeRequest, PaginatedRequest {
 
-		default String progressToken() {
+		default Object progressToken() {
 			if (meta() != null && meta().containsKey("progressToken")) {
-				return meta().get("progressToken").toString();
+				return meta().get("progressToken");
 			}
 			return null;
 		}
@@ -1502,7 +1502,7 @@ public Builder meta(Map meta) {
 				return this;
 			}
 
-			public Builder progressToken(String progressToken) {
+			public Builder progressToken(Object progressToken) {
 				if (this.meta == null) {
 					this.meta = new HashMap<>();
 				}
@@ -1912,7 +1912,7 @@ public Builder meta(Map meta) {
 				return this;
 			}
 
-			public Builder progressToken(String progressToken) {
+			public Builder progressToken(Object progressToken) {
 				if (this.meta == null) {
 					this.meta = new HashMap<>();
 				}
@@ -2080,7 +2080,7 @@ public Builder meta(Map meta) {
 				return this;
 			}
 
-			public Builder progressToken(String progressToken) {
+			public Builder progressToken(Object progressToken) {
 				if (this.meta == null) {
 					this.meta = new HashMap<>();
 				}
@@ -2217,13 +2217,13 @@ public record PaginatedResult(@JsonProperty("nextCursor") String nextCursor) {
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
 	@JsonIgnoreProperties(ignoreUnknown = true)
 	public record ProgressNotification( // @formatter:off
-		@JsonProperty("progressToken") String progressToken,
+		@JsonProperty("progressToken") Object progressToken,
 		@JsonProperty("progress") Double progress,
 		@JsonProperty("total") Double total,
 		@JsonProperty("message") String message,
 		@JsonProperty("_meta") Map meta) implements Notification { // @formatter:on
 
-		public ProgressNotification(String progressToken, double progress, Double total, String message) {
+		public ProgressNotification(Object progressToken, double progress, Double total, String message) {
 			this(progressToken, progress, total, message, null);
 		}
 	}

From e3079270d50dc035cbedde7102ce280bd23eaad3 Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Wed, 12 Nov 2025 16:13:08 +0100
Subject: [PATCH 107/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       |  2 +-
 mcp-core/pom.xml                      |  6 +++---
 mcp-json-jackson2/pom.xml             |  4 ++--
 mcp-json/pom.xml                      |  2 +-
 mcp-spring/mcp-spring-webflux/pom.xml |  8 ++++----
 mcp-spring/mcp-spring-webmvc/pom.xml  | 10 +++++-----
 mcp-test/pom.xml                      |  4 ++--
 mcp/pom.xml                           |  6 +++---
 pom.xml                               |  2 +-
 9 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index fc08f3d67..b06baea81 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.16.0-SNAPSHOT
+        0.17.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-core/pom.xml b/mcp-core/pom.xml
index 6ac8c2aba..39b4c9dc7 100644
--- a/mcp-core/pom.xml
+++ b/mcp-core/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.16.0-SNAPSHOT
+		0.17.0-SNAPSHOT
 	
 	mcp-core
 	jar
@@ -68,7 +68,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.16.0-SNAPSHOT
+            0.17.0-SNAPSHOT
         
 
 		
@@ -101,7 +101,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.16.0-SNAPSHOT
+            0.17.0-SNAPSHOT
             test
         
 
diff --git a/mcp-json-jackson2/pom.xml b/mcp-json-jackson2/pom.xml
index 7e7000b97..8ea1fa7d2 100644
--- a/mcp-json-jackson2/pom.xml
+++ b/mcp-json-jackson2/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.16.0-SNAPSHOT
+		0.17.0-SNAPSHOT
 	
 	mcp-json-jackson2
 	jar
@@ -37,7 +37,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.16.0-SNAPSHOT
+            0.17.0-SNAPSHOT
         
         
             com.fasterxml.jackson.core
diff --git a/mcp-json/pom.xml b/mcp-json/pom.xml
index c12801fd4..9fc850e11 100644
--- a/mcp-json/pom.xml
+++ b/mcp-json/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.16.0-SNAPSHOT
+		0.17.0-SNAPSHOT
 	
 	mcp-json
 	jar
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index c9b85f51d..594d95750 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.16.0-SNAPSHOT
+		0.17.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,19 +25,19 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.16.0-SNAPSHOT
+            0.17.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 94b5c5881..6460f652f 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.16.0-SNAPSHOT
+		0.17.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,13 +25,13 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.16.0-SNAPSHOT
+            0.17.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 		
 
 		
@@ -43,14 +43,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 			test
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 7618779b6..3fbd028f4 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.16.0-SNAPSHOT
+		0.17.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index ce4fd7552..270dc2a1f 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.16.0-SNAPSHOT
+		0.17.0-SNAPSHOT
 	
 	mcp
 	jar
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-json-jackson2
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-core
-			0.16.0-SNAPSHOT
+			0.17.0-SNAPSHOT
 		
 	
 
diff --git a/pom.xml b/pom.xml
index 1ff45596e..ca9ce7be4 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.16.0-SNAPSHOT
+	0.17.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From 2d22868e1ecc0908c1a1472f618ebfcb0ec7667c Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Tue, 18 Nov 2025 10:20:08 +0100
Subject: [PATCH 108/125] Fix experimental client capabilities tests (#670)

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../client/AbstractMcpAsyncClientTests.java                     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 859dc5f82..57a223ea2 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -673,7 +673,7 @@ void testInitializeWithElicitationCapability() {
 	@Test
 	void testInitializeWithAllCapabilities() {
 		var capabilities = ClientCapabilities.builder()
-			.experimental(Map.of("feature", "test"))
+			.experimental(Map.of("feature", Map.of("featureFlag", true)))
 			.roots(true)
 			.sampling()
 			.build();

From bc308573f3b4daf71fe4bb166f5f6e4c1c4bb9d7 Mon Sep 17 00:00:00 2001
From: mingo007 
Date: Tue, 11 Nov 2025 22:00:30 +0800
Subject: [PATCH 109/125] Fix typo in test name: testPingWithEaxctExceptionType
 -> testPingWithExactExceptionType

---
 .../client/HttpSseMcpAsyncClientLostConnectionTests.java        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
index ba740518b..30e7fe913 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
@@ -122,7 +122,7 @@ void withClient(McpClientTransport transport, Consumer c) {
 	}
 
 	@Test
-	void testPingWithEaxctExceptionType() {
+	void testPingWithExactExceptionType() {
 		withClient(HttpClientSseClientTransport.builder(host).build(), mcpAsyncClient -> {
 			StepVerifier.create(mcpAsyncClient.initialize()).expectNextCount(1).verifyComplete();
 

From 87bdf1ee49bba050d112522ceed56dac3014fb4b Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Tue, 18 Nov 2025 14:53:50 +0100
Subject: [PATCH 110/125] Client transports: make #protocolVersions()
 configurable (#669)

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../HttpClientStreamableHttpTransport.java    |  68 ++++++--
 ...ttpVersionNegotiationIntegrationTests.java | 143 +++++++++++++++++
 .../McpTestRequestRecordingServletFilter.java | 128 +++++++++++++++
 .../transport/McpTestServletFilter.java       |  43 ------
 .../server/transport/TomcatTestUtil.java      |  22 +--
 .../WebClientStreamableHttpTransport.java     |  57 +++++--
 ...ttpVersionNegotiationIntegrationTests.java | 146 ++++++++++++++++++
 ...equestRecordingExchangeFilterFunction.java |  53 +++++++
 8 files changed, 580 insertions(+), 80 deletions(-)
 create mode 100644 mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java
 create mode 100644 mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java
 delete mode 100644 mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java
 create mode 100644 mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java

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 cd8fa171f..c48aedbcf 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
@@ -11,6 +11,8 @@
 import java.net.http.HttpResponse;
 import java.net.http.HttpResponse.BodyHandler;
 import java.time.Duration;
+import java.util.Collections;
+import java.util.Comparator;
 import java.util.List;
 import java.util.Optional;
 import java.util.concurrent.CompletionException;
@@ -18,17 +20,12 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
-import org.reactivestreams.Publisher;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import io.modelcontextprotocol.json.TypeRef;
-import io.modelcontextprotocol.json.McpJsonMapper;
-
+import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
-import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.ClosedMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
@@ -42,6 +39,9 @@
 import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
+import org.reactivestreams.Publisher;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import reactor.core.Disposable;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.FluxSink;
@@ -78,8 +78,6 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(HttpClientStreamableHttpTransport.class);
 
-	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_06_18;
-
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
 	/**
@@ -125,9 +123,14 @@ public class HttpClientStreamableHttpTransport implements McpClientTransport {
 
 	private final AtomicReference> exceptionHandler = new AtomicReference<>();
 
+	private final List supportedProtocolVersions;
+
+	private final String latestSupportedProtocolVersion;
+
 	private HttpClientStreamableHttpTransport(McpJsonMapper jsonMapper, HttpClient httpClient,
 			HttpRequest.Builder requestBuilder, String baseUri, String endpoint, boolean resumableStreams,
-			boolean openConnectionOnStartup, McpAsyncHttpClientRequestCustomizer httpRequestCustomizer) {
+			boolean openConnectionOnStartup, McpAsyncHttpClientRequestCustomizer httpRequestCustomizer,
+			List supportedProtocolVersions) {
 		this.jsonMapper = jsonMapper;
 		this.httpClient = httpClient;
 		this.requestBuilder = requestBuilder;
@@ -137,12 +140,16 @@ private HttpClientStreamableHttpTransport(McpJsonMapper jsonMapper, HttpClient h
 		this.openConnectionOnStartup = openConnectionOnStartup;
 		this.activeSession.set(createTransportSession());
 		this.httpRequestCustomizer = httpRequestCustomizer;
+		this.supportedProtocolVersions = Collections.unmodifiableList(supportedProtocolVersions);
+		this.latestSupportedProtocolVersion = this.supportedProtocolVersions.stream()
+			.sorted(Comparator.reverseOrder())
+			.findFirst()
+			.get();
 	}
 
 	@Override
 	public List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26,
-				ProtocolVersions.MCP_2025_06_18);
+		return supportedProtocolVersions;
 	}
 
 	public static Builder builder(String baseUri) {
@@ -186,7 +193,7 @@ private Publisher createDelete(String sessionId) {
 				.uri(uri)
 				.header("Cache-Control", "no-cache")
 				.header(HttpHeaders.MCP_SESSION_ID, sessionId)
-				.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
+				.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
 				.DELETE();
 			var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
 			return Mono.from(this.httpRequestCustomizer.customize(builder, "DELETE", uri, null, transportContext));
@@ -257,7 +264,7 @@ private Mono reconnect(McpTransportStream stream) {
 				var builder = requestBuilder.uri(uri)
 					.header(HttpHeaders.ACCEPT, TEXT_EVENT_STREAM)
 					.header("Cache-Control", "no-cache")
-					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
+					.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
 					.GET();
 				var transportContext = connectionCtx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
 				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null, transportContext));
@@ -432,7 +439,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 					.header(HttpHeaders.ACCEPT, APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
 					.header(HttpHeaders.CONTENT_TYPE, APPLICATION_JSON)
 					.header(HttpHeaders.CACHE_CONTROL, "no-cache")
-					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
+					.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
 					.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
 				var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
 				return Mono
@@ -624,6 +631,9 @@ public static class Builder {
 
 		private Duration connectTimeout = Duration.ofSeconds(10);
 
+		private List supportedProtocolVersions = List.of(ProtocolVersions.MCP_2024_11_05,
+				ProtocolVersions.MCP_2025_03_26, ProtocolVersions.MCP_2025_06_18);
+
 		/**
 		 * Creates a new builder with the specified base URI.
 		 * @param baseUri the base URI of the MCP server
@@ -772,6 +782,30 @@ public Builder connectTimeout(Duration connectTimeout) {
 			return this;
 		}
 
+		/**
+		 * Sets the list of supported protocol versions used in version negotiation. By
+		 * default, the client will send the latest of those versions in the
+		 * {@code MCP-Protocol-Version} header.
+		 * 

+		 * Setting this value only updates the values used in version negotiation, and
+		 * does NOT impact the actual capabilities of the transport. It should only be
+		 * used for compatibility with servers having strict requirements around the
+		 * {@code MCP-Protocol-Version} header.
+		 * @param supportedProtocolVersions protocol versions supported by this transport
+		 * @return this builder
+		 * @see version
+		 * negotiation specification
+		 * @see Protocol
+		 * Version Header
+		 */
+		public Builder supportedProtocolVersions(List supportedProtocolVersions) {
+			Assert.notEmpty(supportedProtocolVersions, "supportedProtocolVersions must not be empty");
+			this.supportedProtocolVersions = Collections.unmodifiableList(supportedProtocolVersions);
+			return this;
+		}
+
 		/**
 		 * Construct a fresh instance of {@link HttpClientStreamableHttpTransport} using
 		 * the current builder configuration.
@@ -781,7 +815,7 @@ public HttpClientStreamableHttpTransport build() {
 			HttpClient httpClient = this.clientBuilder.connectTimeout(this.connectTimeout).build();
 			return new HttpClientStreamableHttpTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
 					httpClient, requestBuilder, baseUri, endpoint, resumableStreams, openConnectionOnStartup,
-					httpRequestCustomizer);
+					httpRequestCustomizer, supportedProtocolVersions);
 		}
 
 	}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java
new file mode 100644
index 000000000..12a3ef9c6
--- /dev/null
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java
@@ -0,0 +1,143 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.common;
+
+import java.util.List;
+import java.util.Map;
+import java.util.function.BiFunction;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpSyncServer;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.server.transport.McpTestRequestRecordingServletFilter;
+import io.modelcontextprotocol.server.transport.TomcatTestUtil;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.ProtocolVersions;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.apache.catalina.startup.Tomcat;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class HttpClientStreamableHttpVersionNegotiationIntegrationTests {
+
+	private Tomcat tomcat;
+
+	private static final int PORT = TomcatTestUtil.findAvailablePort();
+
+	private final McpTestRequestRecordingServletFilter requestRecordingFilter = new McpTestRequestRecordingServletFilter();
+
+	private final HttpServletStreamableServerTransportProvider transport = HttpServletStreamableServerTransportProvider
+		.builder()
+		.contextExtractor(
+				req -> McpTransportContext.create(Map.of("protocol-version", req.getHeader("MCP-protocol-version"))))
+		.build();
+
+	private final McpSchema.Tool toolSpec = McpSchema.Tool.builder()
+		.name("test-tool")
+		.description("return the protocol version used")
+		.build();
+
+	private final BiFunction toolHandler = (
+			exchange, request) -> new McpSchema.CallToolResult(
+					exchange.transportContext().get("protocol-version").toString(), null);
+
+	McpSyncServer mcpServer = McpServer.sync(transport)
+		.capabilities(McpSchema.ServerCapabilities.builder().tools(false).build())
+		.tools(new McpServerFeatures.SyncToolSpecification(toolSpec, null, toolHandler))
+		.build();
+
+	@AfterEach
+	void tearDown() {
+		stopTomcat();
+	}
+
+	@Test
+	void usesLatestVersion() {
+		startTomcat();
+
+		var client = McpClient.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT).build())
+			.build();
+
+		client.initialize();
+		McpSchema.CallToolResult response = client.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		var calls = requestRecordingFilter.getCalls();
+
+		assertThat(calls).filteredOn(c -> !c.body().contains("\"method\":\"initialize\""))
+			// GET /mcp ; POST notification/initialized ; POST tools/call
+			.hasSize(3)
+			.map(McpTestRequestRecordingServletFilter.Call::headers)
+			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version",
+					ProtocolVersions.MCP_2025_06_18));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo(ProtocolVersions.MCP_2025_06_18);
+		mcpServer.close();
+	}
+
+	@Test
+	void usesCustomLatestVersion() {
+		startTomcat();
+
+		var transport = HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+			.supportedProtocolVersions(List.of(ProtocolVersions.MCP_2025_06_18, "2263-03-18"))
+			.build();
+		var client = McpClient.sync(transport).build();
+
+		client.initialize();
+		McpSchema.CallToolResult response = client.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		var calls = requestRecordingFilter.getCalls();
+
+		assertThat(calls).filteredOn(c -> !c.body().contains("\"method\":\"initialize\""))
+			// GET /mcp ; POST notification/initialized ; POST tools/call
+			.hasSize(3)
+			.map(McpTestRequestRecordingServletFilter.Call::headers)
+			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version", "2263-03-18"));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("2263-03-18");
+		mcpServer.close();
+	}
+
+	private void startTomcat() {
+		tomcat = TomcatTestUtil.createTomcatServer("", PORT, transport, requestRecordingFilter);
+		try {
+			tomcat.start();
+			assertThat(tomcat.getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+	}
+
+	private void stopTomcat() {
+		if (tomcat != null) {
+			try {
+				tomcat.stop();
+				tomcat.destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java
new file mode 100644
index 000000000..09f0d305d
--- /dev/null
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java
@@ -0,0 +1,128 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server.transport;
+
+import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+import jakarta.servlet.Filter;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ReadListener;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.ServletInputStream;
+import jakarta.servlet.ServletRequest;
+import jakarta.servlet.ServletResponse;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletRequestWrapper;
+
+/**
+ * Simple {@link Filter} which records calls made to an MCP server.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+public class McpTestRequestRecordingServletFilter implements Filter {
+
+	private final List calls = new ArrayList<>();
+
+	@Override
+	public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
+			throws IOException, ServletException {
+
+		if (servletRequest instanceof HttpServletRequest req) {
+			var headers = Collections.list(req.getHeaderNames())
+				.stream()
+				.collect(Collectors.toUnmodifiableMap(Function.identity(),
+						name -> String.join(",", Collections.list(req.getHeaders(name)))));
+			var request = new CachedBodyHttpServletRequest(req);
+			calls.add(new Call(headers, request.getBodyAsString()));
+			filterChain.doFilter(request, servletResponse);
+		}
+		else {
+			filterChain.doFilter(servletRequest, servletResponse);
+		}
+
+	}
+
+	public List getCalls() {
+
+		return List.copyOf(calls);
+	}
+
+	public record Call(Map headers, String body) {
+
+	}
+
+	public static class CachedBodyHttpServletRequest extends HttpServletRequestWrapper {
+
+		private final byte[] cachedBody;
+
+		public CachedBodyHttpServletRequest(HttpServletRequest request) throws IOException {
+			super(request);
+			this.cachedBody = request.getInputStream().readAllBytes();
+		}
+
+		@Override
+		public ServletInputStream getInputStream() {
+			return new CachedBodyServletInputStream(cachedBody);
+		}
+
+		@Override
+		public BufferedReader getReader() {
+			return new BufferedReader(new InputStreamReader(getInputStream(), StandardCharsets.UTF_8));
+		}
+
+		public String getBodyAsString() {
+			return new String(cachedBody, StandardCharsets.UTF_8);
+		}
+
+	}
+
+	public static class CachedBodyServletInputStream extends ServletInputStream {
+
+		private InputStream cachedBodyInputStream;
+
+		public CachedBodyServletInputStream(byte[] cachedBody) {
+			this.cachedBodyInputStream = new ByteArrayInputStream(cachedBody);
+		}
+
+		@Override
+		public boolean isFinished() {
+			try {
+				return cachedBodyInputStream.available() == 0;
+			}
+			catch (IOException e) {
+				e.printStackTrace();
+			}
+			return false;
+		}
+
+		@Override
+		public boolean isReady() {
+			return true;
+		}
+
+		@Override
+		public void setReadListener(ReadListener readListener) {
+			throw new UnsupportedOperationException();
+		}
+
+		@Override
+		public int read() throws IOException {
+			return cachedBodyInputStream.read();
+		}
+
+	}
+
+}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java
deleted file mode 100644
index cc2543aa9..000000000
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestServletFilter.java
+++ /dev/null
@@ -1,43 +0,0 @@
-/*
- * Copyright 2025 - 2025 the original author or authors.
- */
-
-package io.modelcontextprotocol.server.transport;
-
-import java.io.IOException;
-
-import jakarta.servlet.Filter;
-import jakarta.servlet.FilterChain;
-import jakarta.servlet.ServletException;
-import jakarta.servlet.ServletRequest;
-import jakarta.servlet.ServletResponse;
-
-/**
- * Simple {@link Filter} which sets a value in a thread local. Used to verify whether MCP
- * executions happen on the thread processing the request or are offloaded.
- *
- * @author Daniel Garnier-Moiroux
- */
-public class McpTestServletFilter implements Filter {
-
-	public static final String THREAD_LOCAL_VALUE = McpTestServletFilter.class.getName();
-
-	private static final ThreadLocal holder = new ThreadLocal<>();
-
-	@Override
-	public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
-			throws IOException, ServletException {
-		holder.set(THREAD_LOCAL_VALUE);
-		try {
-			filterChain.doFilter(servletRequest, servletResponse);
-		}
-		finally {
-			holder.remove();
-		}
-	}
-
-	public static String getThreadLocalValue() {
-		return holder.get();
-	}
-
-}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
index 2cf95dc94..490e29838 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/TomcatTestUtil.java
@@ -8,6 +8,7 @@
 import java.net.InetSocketAddress;
 import java.net.ServerSocket;
 
+import jakarta.servlet.Filter;
 import jakarta.servlet.Servlet;
 import org.apache.catalina.Context;
 import org.apache.catalina.startup.Tomcat;
@@ -24,7 +25,8 @@ public class TomcatTestUtil {
 		// Prevent instantiation
 	}
 
-	public static Tomcat createTomcatServer(String contextPath, int port, Servlet servlet) {
+	public static Tomcat createTomcatServer(String contextPath, int port, Servlet servlet,
+			Filter... additionalFilters) {
 
 		var tomcat = new Tomcat();
 		tomcat.setPort(port);
@@ -43,15 +45,17 @@ public static Tomcat createTomcatServer(String contextPath, int port, Servlet se
 		context.addChild(wrapper);
 		context.addServletMappingDecoded("/*", "mcpServlet");
 
-		var filterDef = new FilterDef();
-		filterDef.setFilterClass(McpTestServletFilter.class.getName());
-		filterDef.setFilterName(McpTestServletFilter.class.getSimpleName());
-		context.addFilterDef(filterDef);
+		for (var filter : additionalFilters) {
+			var filterDef = new FilterDef();
+			filterDef.setFilter(filter);
+			filterDef.setFilterName(McpTestRequestRecordingServletFilter.class.getSimpleName());
+			context.addFilterDef(filterDef);
 
-		var filterMap = new FilterMap();
-		filterMap.setFilterName(McpTestServletFilter.class.getSimpleName());
-		filterMap.addURLPattern("/*");
-		context.addFilterMap(filterMap);
+			var filterMap = new FilterMap();
+			filterMap.setFilterName(McpTestRequestRecordingServletFilter.class.getSimpleName());
+			filterMap.addURLPattern("/*");
+			context.addFilterMap(filterMap);
+		}
 
 		var connector = tomcat.getConnector();
 		connector.setAsyncTimeout(3000);
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 5ec272961..b67d34f6b 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -5,6 +5,8 @@
 package io.modelcontextprotocol.client.transport;
 
 import java.io.IOException;
+import java.util.Collections;
+import java.util.Comparator;
 import java.util.List;
 import java.util.Optional;
 import java.util.concurrent.atomic.AtomicReference;
@@ -22,9 +24,8 @@
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.client.WebClientResponseException;
 
-import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.json.McpJsonMapper;
-
+import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.ClosedMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportStream;
@@ -76,8 +77,6 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 
 	private static final Logger logger = LoggerFactory.getLogger(WebClientStreamableHttpTransport.class);
 
-	private static final String MCP_PROTOCOL_VERSION = ProtocolVersions.MCP_2025_06_18;
-
 	private static final String DEFAULT_ENDPOINT = "/mcp";
 
 	/**
@@ -105,20 +104,29 @@ public class WebClientStreamableHttpTransport implements McpClientTransport {
 
 	private final AtomicReference> exceptionHandler = new AtomicReference<>();
 
+	private final List supportedProtocolVersions;
+
+	private final String latestSupportedProtocolVersion;
+
 	private WebClientStreamableHttpTransport(McpJsonMapper jsonMapper, WebClient.Builder webClientBuilder,
-			String endpoint, boolean resumableStreams, boolean openConnectionOnStartup) {
+			String endpoint, boolean resumableStreams, boolean openConnectionOnStartup,
+			List supportedProtocolVersions) {
 		this.jsonMapper = jsonMapper;
 		this.webClient = webClientBuilder.build();
 		this.endpoint = endpoint;
 		this.resumableStreams = resumableStreams;
 		this.openConnectionOnStartup = openConnectionOnStartup;
 		this.activeSession.set(createTransportSession());
+		this.supportedProtocolVersions = List.copyOf(supportedProtocolVersions);
+		this.latestSupportedProtocolVersion = this.supportedProtocolVersions.stream()
+			.sorted(Comparator.reverseOrder())
+			.findFirst()
+			.get();
 	}
 
 	@Override
 	public List protocolVersions() {
-		return List.of(ProtocolVersions.MCP_2024_11_05, ProtocolVersions.MCP_2025_03_26,
-				ProtocolVersions.MCP_2025_06_18);
+		return supportedProtocolVersions;
 	}
 
 	/**
@@ -149,7 +157,7 @@ private McpTransportSession createTransportSession() {
 				: webClient.delete()
 					.uri(this.endpoint)
 					.header(HttpHeaders.MCP_SESSION_ID, sessionId)
-					.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
+					.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
 					.retrieve()
 					.toBodilessEntity()
 					.onErrorComplete(e -> {
@@ -217,7 +225,7 @@ private Mono reconnect(McpTransportStream stream) {
 			Disposable connection = webClient.get()
 				.uri(this.endpoint)
 				.accept(MediaType.TEXT_EVENT_STREAM)
-				.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
+				.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
 				.headers(httpHeaders -> {
 					transportSession.sessionId().ifPresent(id -> httpHeaders.add(HttpHeaders.MCP_SESSION_ID, id));
 					if (stream != null) {
@@ -283,7 +291,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			Disposable connection = webClient.post()
 				.uri(this.endpoint)
 				.accept(MediaType.APPLICATION_JSON, MediaType.TEXT_EVENT_STREAM)
-				.header(HttpHeaders.PROTOCOL_VERSION, MCP_PROTOCOL_VERSION)
+				.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
 				.headers(httpHeaders -> {
 					transportSession.sessionId().ifPresent(id -> httpHeaders.add(HttpHeaders.MCP_SESSION_ID, id));
 				})
@@ -495,6 +503,9 @@ public static class Builder {
 
 		private boolean openConnectionOnStartup = false;
 
+		private List supportedProtocolVersions = List.of(ProtocolVersions.MCP_2024_11_05,
+				ProtocolVersions.MCP_2025_03_26, ProtocolVersions.MCP_2025_06_18);
+
 		private Builder(WebClient.Builder webClientBuilder) {
 			Assert.notNull(webClientBuilder, "WebClient.Builder must not be null");
 			this.webClientBuilder = webClientBuilder;
@@ -560,6 +571,30 @@ public Builder openConnectionOnStartup(boolean openConnectionOnStartup) {
 			return this;
 		}
 
+		/**
+		 * Sets the list of supported protocol versions used in version negotiation. By
+		 * default, the client will send the latest of those versions in the
+		 * {@code MCP-Protocol-Version} header.
+		 * 

+		 * Setting this value only updates the values used in version negotiation, and
+		 * does NOT impact the actual capabilities of the transport. It should only be
+		 * used for compatibility with servers having strict requirements around the
+		 * {@code MCP-Protocol-Version} header.
+		 * @param supportedProtocolVersions protocol versions supported by this transport
+		 * @return this builder
+		 * @see version
+		 * negotiation specification
+		 * @see Protocol
+		 * Version Header
+		 */
+		public Builder supportedProtocolVersions(List supportedProtocolVersions) {
+			Assert.notEmpty(supportedProtocolVersions, "supportedProtocolVersions must not be empty");
+			this.supportedProtocolVersions = Collections.unmodifiableList(supportedProtocolVersions);
+			return this;
+		}
+
 		/**
 		 * Construct a fresh instance of {@link WebClientStreamableHttpTransport} using
 		 * the current builder configuration.
@@ -567,7 +602,7 @@ public Builder openConnectionOnStartup(boolean openConnectionOnStartup) {
 		 */
 		public WebClientStreamableHttpTransport build() {
 			return new WebClientStreamableHttpTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
-					webClientBuilder, endpoint, resumableStreams, openConnectionOnStartup);
+					webClientBuilder, endpoint, resumableStreams, openConnectionOnStartup, supportedProtocolVersions);
 		}
 
 	}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java
new file mode 100644
index 000000000..7627bd419
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java
@@ -0,0 +1,146 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.function.BiFunction;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpServerFeatures;
+import io.modelcontextprotocol.server.McpSyncServer;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.transport.WebFluxStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.ProtocolVersions;
+import io.modelcontextprotocol.utils.McpTestRequestRecordingExchangeFilterFunction;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.web.reactive.function.client.WebClient;
+import org.springframework.web.reactive.function.server.RouterFunction;
+import org.springframework.web.reactive.function.server.RouterFunctions;
+import org.springframework.web.reactive.function.server.ServerResponse;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class WebFluxStreamableHttpVersionNegotiationIntegrationTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private DisposableServer httpServer;
+
+	private final McpTestRequestRecordingExchangeFilterFunction recordingFilterFunction = new McpTestRequestRecordingExchangeFilterFunction();
+
+	private final McpSchema.Tool toolSpec = McpSchema.Tool.builder()
+		.name("test-tool")
+		.description("return the protocol version used")
+		.build();
+
+	private final BiFunction toolHandler = (
+			exchange, request) -> new McpSchema.CallToolResult(
+					exchange.transportContext().get("protocol-version").toString(), null);
+
+	private final WebFluxStreamableServerTransportProvider mcpStreamableServerTransportProvider = WebFluxStreamableServerTransportProvider
+		.builder()
+		.contextExtractor(req -> McpTransportContext
+			.create(Map.of("protocol-version", req.headers().firstHeader("MCP-protocol-version"))))
+		.build();
+
+	private final McpSyncServer mcpServer = McpServer.sync(mcpStreamableServerTransportProvider)
+		.capabilities(McpSchema.ServerCapabilities.builder().tools(false).build())
+		.tools(new McpServerFeatures.SyncToolSpecification(toolSpec, null, toolHandler))
+		.build();
+
+	@BeforeEach
+	void setUp() {
+		RouterFunction filteredRouter = mcpStreamableServerTransportProvider.getRouterFunction()
+			.filter(recordingFilterFunction);
+
+		HttpHandler httpHandler = RouterFunctions.toHttpHandler(filteredRouter);
+
+		ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(httpHandler);
+
+		this.httpServer = HttpServer.create().port(PORT).handle(adapter).bindNow();
+	}
+
+	@AfterEach
+	public void after() {
+		if (httpServer != null) {
+			httpServer.disposeNow();
+		}
+		if (mcpServer != null) {
+			mcpServer.close();
+		}
+	}
+
+	@Test
+	void usesLatestVersion() {
+		var client = McpClient
+			.sync(WebClientStreamableHttpTransport.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
+				.build())
+			.requestTimeout(Duration.ofHours(10))
+			.build();
+
+		client.initialize();
+
+		McpSchema.CallToolResult response = client.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		var calls = recordingFilterFunction.getCalls();
+		assertThat(calls).filteredOn(c -> !c.body().contains("\"method\":\"initialize\""))
+			// GET /mcp ; POST notification/initialized ; POST tools/call
+			.hasSize(3)
+			.map(McpTestRequestRecordingExchangeFilterFunction.Call::headers)
+			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version",
+					ProtocolVersions.MCP_2025_06_18));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo(ProtocolVersions.MCP_2025_06_18);
+		mcpServer.close();
+	}
+
+	@Test
+	void usesCustomLatestVersion() {
+		var transport = WebClientStreamableHttpTransport
+			.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
+			.supportedProtocolVersions(List.of(ProtocolVersions.MCP_2025_06_18, "2263-03-18"))
+			.build();
+		var client = McpClient.sync(transport).requestTimeout(Duration.ofHours(10)).build();
+
+		client.initialize();
+
+		McpSchema.CallToolResult response = client.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
+
+		var calls = recordingFilterFunction.getCalls();
+		assertThat(calls).filteredOn(c -> !c.body().contains("\"method\":\"initialize\""))
+			// GET /mcp ; POST notification/initialized ; POST tools/call
+			.hasSize(3)
+			.map(McpTestRequestRecordingExchangeFilterFunction.Call::headers)
+			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version", "2263-03-18"));
+
+		assertThat(response).isNotNull();
+		assertThat(response.content()).hasSize(1)
+			.first()
+			.extracting(McpSchema.TextContent.class::cast)
+			.extracting(McpSchema.TextContent::text)
+			.isEqualTo("2263-03-18");
+		mcpServer.close();
+	}
+
+}
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java
new file mode 100644
index 000000000..5600795c1
--- /dev/null
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2025-2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.utils;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import reactor.core.publisher.Mono;
+
+import org.springframework.web.reactive.function.server.HandlerFilterFunction;
+import org.springframework.web.reactive.function.server.HandlerFunction;
+import org.springframework.web.reactive.function.server.ServerRequest;
+import org.springframework.web.reactive.function.server.ServerResponse;
+
+/**
+ * Simple {@link HandlerFilterFunction} which records calls made to an MCP server.
+ *
+ * @author Daniel Garnier-Moiroux
+ */
+public class McpTestRequestRecordingExchangeFilterFunction implements HandlerFilterFunction {
+
+	private final List calls = new ArrayList<>();
+
+	@Override
+	public Mono filter(ServerRequest request, HandlerFunction next) {
+		Map headers = request.headers()
+			.asHttpHeaders()
+			.keySet()
+			.stream()
+			.collect(Collectors.toMap(String::toLowerCase, k -> String.join(",", request.headers().header(k))));
+
+		var cr = request.bodyToMono(String.class).defaultIfEmpty("").map(body -> {
+			this.calls.add(new Call(headers, body));
+			return ServerRequest.from(request).body(body).build();
+		});
+
+		return cr.flatMap(next::handle);
+
+	}
+
+	public List getCalls() {
+		return List.copyOf(calls);
+	}
+
+	public record Call(Map headers, String body) {
+
+	}
+
+}

From 67f8eabb7a0ab70b43b5223768b3aaafd243c843 Mon Sep 17 00:00:00 2001
From: "He-Pin(kerr)" 
Date: Wed, 19 Nov 2025 17:50:44 +0800
Subject: [PATCH 111/125] WebClientStreamableHttpTransport: use Spring-5
 compatible methods (#649)

Signed-off-by: He-Pin 
Signed-off-by: Daniel Garnier-Moiroux 
---
 .../WebClientStreamableHttpTransport.java     | 49 ++++++++++++++-----
 1 file changed, 37 insertions(+), 12 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index b67d34f6b..6b1d6ba8a 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -308,7 +308,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 
 					// The spec mentions only ACCEPTED, but the existing SDKs can return
 					// 200 OK for notifications
-					if (response.statusCode().is2xxSuccessful()) {
+					if (is2xx(response)) {
 						Optional contentType = response.headers().contentType();
 						long contentLength = response.headers().contentLength().orElse(-1);
 						// Existing SDKs consume notifications with no response body nor
@@ -392,14 +392,15 @@ private Flux extractError(ClientResponse response, Str
 			}
 			catch (IOException ex) {
 				toPropagate = new McpTransportException("Sending request failed, " + e.getMessage(), e);
-				logger.debug("Received content together with {} HTTP code response: {}", response.statusCode(), body);
+				logger.debug("Received content together with {} HTTP code response: {}", response.rawStatusCode(),
+						body);
 			}
 
 			// Some implementations can return 400 when presented with a
 			// session id that it doesn't know about, so we will
 			// invalidate the session
 			// https://github.com/modelcontextprotocol/typescript-sdk/issues/389
-			if (responseException.getStatusCode().isSameCodeAs(HttpStatus.BAD_REQUEST)) {
+			if (isBadRequest(responseException)) {
 				if (!sessionRepresentation.equals(MISSING_SESSION_ID)) {
 					return Mono.error(new McpTransportSessionNotFoundException(sessionRepresentation, toPropagate));
 				}
@@ -419,16 +420,8 @@ private Flux eventStream(McpTransportStream= 200 && response.rawStatusCode() < 300;
+	}
+
 }

From 86991c1e4951d13fbbc68961ad0b315313772b65 Mon Sep 17 00:00:00 2001
From: lance 
Date: Thu, 30 Oct 2025 22:57:58 +0800
Subject: [PATCH 112/125] fix the baseUrl is configured with a trailing slash

Signed-off-by: lance 
Signed-off-by: Daniel Garnier-Moiroux 
---
 ...HttpServletSseServerTransportProvider.java |  67 +++++++---
 .../WebFluxSseServerTransportProvider.java    |  29 +++--
 .../WebMvcSseServerTransportProvider.java     |  40 ++++--
 ...WebMvcSseServerTransportProviderTests.java | 119 ++++++++++++++++++
 4 files changed, 221 insertions(+), 34 deletions(-)
 create mode 100644 mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProviderTests.java

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
index 4739e231a..96cebb74a 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/transport/HttpServletSseServerTransportProvider.java
@@ -14,9 +14,9 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicBoolean;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
-import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -69,7 +69,9 @@
 @WebServlet(asyncSupported = true)
 public class HttpServletSseServerTransportProvider extends HttpServlet implements McpServerTransportProvider {
 
-	/** Logger for this class */
+	/**
+	 * Logger for this class
+	 */
 	private static final Logger logger = LoggerFactory.getLogger(HttpServletSseServerTransportProvider.class);
 
 	public static final String UTF_8 = "UTF-8";
@@ -78,38 +80,60 @@ public class HttpServletSseServerTransportProvider extends HttpServlet implement
 
 	public static final String FAILED_TO_SEND_ERROR_RESPONSE = "Failed to send error response: {}";
 
-	/** Default endpoint path for SSE connections */
+	/**
+	 * Default endpoint path for SSE connections
+	 */
 	public static final String DEFAULT_SSE_ENDPOINT = "/sse";
 
-	/** Event type for regular messages */
+	/**
+	 * Event type for regular messages
+	 */
 	public static final String MESSAGE_EVENT_TYPE = "message";
 
-	/** Event type for endpoint information */
+	/**
+	 * Event type for endpoint information
+	 */
 	public static final String ENDPOINT_EVENT_TYPE = "endpoint";
 
+	public static final String SESSION_ID = "sessionId";
+
 	public static final String DEFAULT_BASE_URL = "";
 
-	/** JSON mapper for serialization/deserialization */
+	/**
+	 * JSON mapper for serialization/deserialization
+	 */
 	private final McpJsonMapper jsonMapper;
 
-	/** Base URL for the server transport */
+	/**
+	 * Base URL for the server transport
+	 */
 	private final String baseUrl;
 
-	/** The endpoint path for handling client messages */
+	/**
+	 * The endpoint path for handling client messages
+	 */
 	private final String messageEndpoint;
 
-	/** The endpoint path for handling SSE connections */
+	/**
+	 * The endpoint path for handling SSE connections
+	 */
 	private final String sseEndpoint;
 
-	/** Map of active client sessions, keyed by session ID */
+	/**
+	 * Map of active client sessions, keyed by session ID
+	 */
 	private final Map sessions = new ConcurrentHashMap<>();
 
 	private McpTransportContextExtractor contextExtractor;
 
-	/** Flag indicating if the transport is in the process of shutting down */
+	/**
+	 * Flag indicating if the transport is in the process of shutting down
+	 */
 	private final AtomicBoolean isClosing = new AtomicBoolean(false);
 
-	/** Session factory for creating new sessions */
+	/**
+	 * Session factory for creating new sessions
+	 */
 	private McpServerSession.Factory sessionFactory;
 
 	/**
@@ -243,7 +267,22 @@ protected void doGet(HttpServletRequest request, HttpServletResponse response)
 		this.sessions.put(sessionId, session);
 
 		// Send initial endpoint event
-		this.sendEvent(writer, ENDPOINT_EVENT_TYPE, this.baseUrl + this.messageEndpoint + "?sessionId=" + sessionId);
+		this.sendEvent(writer, ENDPOINT_EVENT_TYPE, buildEndpointUrl(sessionId));
+	}
+
+	/**
+	 * Constructs the full message endpoint URL by combining the base URL, message path,
+	 * and the required session_id query parameter.
+	 * @param sessionId the unique session identifier
+	 * @return the fully qualified endpoint URL as a string
+	 */
+	private String buildEndpointUrl(String sessionId) {
+		// for WebMVC compatibility
+		if (this.baseUrl.endsWith("/")) {
+			return this.baseUrl.substring(0, this.baseUrl.length() - 1) + this.messageEndpoint + "?sessionId="
+					+ sessionId;
+		}
+		return this.baseUrl + this.messageEndpoint + "?sessionId=" + sessionId;
 	}
 
 	/**
@@ -434,8 +473,8 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 		 * Converts data from one type to another using the configured JsonMapper.
 		 * @param data The source data object to convert
 		 * @param typeRef The target type reference
-		 * @return The converted object of type T
 		 * @param  The target type
+		 * @return The converted object of type T
 		 */
 		@Override
 		public  T unmarshalFrom(Object data, TypeRef typeRef) {
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
index 95355c0f2..0c80c5b8b 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/server/transport/WebFluxSseServerTransportProvider.java
@@ -9,10 +9,9 @@
 import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
-
-import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -22,7 +21,6 @@
 import io.modelcontextprotocol.spec.ProtocolVersions;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import reactor.core.Exceptions;
@@ -37,6 +35,7 @@
 import org.springframework.web.reactive.function.server.RouterFunctions;
 import org.springframework.web.reactive.function.server.ServerRequest;
 import org.springframework.web.reactive.function.server.ServerResponse;
+import org.springframework.web.util.UriComponentsBuilder;
 
 /**
  * Server-side implementation of the MCP (Model Context Protocol) HTTP transport using
@@ -95,6 +94,8 @@ public class WebFluxSseServerTransportProvider implements McpServerTransportProv
 	 */
 	public static final String DEFAULT_SSE_ENDPOINT = "/sse";
 
+	public static final String SESSION_ID = "sessionId";
+
 	public static final String DEFAULT_BASE_URL = "";
 
 	private final McpJsonMapper jsonMapper;
@@ -224,6 +225,7 @@ public Mono notifyClients(String method, Object params) {
 	// FIXME: This javadoc makes claims about using isClosing flag but it's not
 	// actually
 	// doing that.
+
 	/**
 	 * Initiates a graceful shutdown of all the sessions. This method ensures all active
 	 * sessions are properly closed and cleaned up.
@@ -286,10 +288,8 @@ private Mono handleSseConnection(ServerRequest request) {
 
 				// Send initial endpoint event
 				logger.debug("Sending initial endpoint event to session: {}", sessionId);
-				sink.next(ServerSentEvent.builder()
-					.event(ENDPOINT_EVENT_TYPE)
-					.data(this.baseUrl + this.messageEndpoint + "?sessionId=" + sessionId)
-					.build());
+				sink.next(
+						ServerSentEvent.builder().event(ENDPOINT_EVENT_TYPE).data(buildEndpointUrl(sessionId)).build());
 				sink.onCancel(() -> {
 					logger.debug("Session {} cancelled", sessionId);
 					sessions.remove(sessionId);
@@ -297,6 +297,21 @@ private Mono handleSseConnection(ServerRequest request) {
 			}).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)), ServerSentEvent.class);
 	}
 
+	/**
+	 * Constructs the full message endpoint URL by combining the base URL, message path,
+	 * and the required session_id query parameter.
+	 * @param sessionId the unique session identifier
+	 * @return the fully qualified endpoint URL as a string
+	 */
+	private String buildEndpointUrl(String sessionId) {
+		// for WebMVC compatibility
+		return UriComponentsBuilder.fromUriString(this.baseUrl)
+			.path(this.messageEndpoint)
+			.queryParam(SESSION_ID, sessionId)
+			.build()
+			.toUriString();
+	}
+
 	/**
 	 * Handles incoming JSON-RPC messages from clients. Deserializes the message and
 	 * processes it through the configured message handler.
diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index 0b71ddc1f..dfaee64b5 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -11,20 +11,18 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
 
+import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
-
-import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.server.McpTransportContextExtractor;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.spec.McpServerTransport;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
 import io.modelcontextprotocol.spec.ProtocolVersions;
-import io.modelcontextprotocol.spec.McpServerSession;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.KeepAliveScheduler;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
@@ -36,6 +34,7 @@
 import org.springframework.web.servlet.function.ServerRequest;
 import org.springframework.web.servlet.function.ServerResponse;
 import org.springframework.web.servlet.function.ServerResponse.SseBuilder;
+import org.springframework.web.util.UriComponentsBuilder;
 
 /**
  * Server-side implementation of the Model Context Protocol (MCP) transport layer using
@@ -87,6 +86,8 @@ public class WebMvcSseServerTransportProvider implements McpServerTransportProvi
 	 */
 	public static final String ENDPOINT_EVENT_TYPE = "endpoint";
 
+	public static final String SESSION_ID = "sessionId";
+
 	/**
 	 * Default SSE endpoint path as specified by the MCP transport specification.
 	 */
@@ -275,9 +276,7 @@ private ServerResponse handleSseConnection(ServerRequest request) {
 				this.sessions.put(sessionId, session);
 
 				try {
-					sseBuilder.id(sessionId)
-						.event(ENDPOINT_EVENT_TYPE)
-						.data(this.baseUrl + this.messageEndpoint + "?sessionId=" + sessionId);
+					sseBuilder.id(sessionId).event(ENDPOINT_EVENT_TYPE).data(buildEndpointUrl(sessionId));
 				}
 				catch (Exception e) {
 					logger.error("Failed to send initial endpoint event: {}", e.getMessage());
@@ -292,6 +291,21 @@ private ServerResponse handleSseConnection(ServerRequest request) {
 		}
 	}
 
+	/**
+	 * Constructs the full message endpoint URL by combining the base URL, message path,
+	 * and the required session_id query parameter.
+	 * @param sessionId the unique session identifier
+	 * @return the fully qualified endpoint URL as a string
+	 */
+	private String buildEndpointUrl(String sessionId) {
+		// for WebMVC compatibility
+		return UriComponentsBuilder.fromUriString(this.baseUrl)
+			.path(this.messageEndpoint)
+			.queryParam(SESSION_ID, sessionId)
+			.build()
+			.toUriString();
+	}
+
 	/**
 	 * Handles incoming JSON-RPC messages from clients. This method:
 	 * 
    
@@ -308,11 +322,11 @@ private ServerResponse handleMessage(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
 		}
 
-		if (request.param("sessionId").isEmpty()) {
+		if (request.param(SESSION_ID).isEmpty()) {
 			return ServerResponse.badRequest().body(new McpError("Session ID missing in message endpoint"));
 		}
 
-		String sessionId = request.param("sessionId").get();
+		String sessionId = request.param(SESSION_ID).get();
 		McpServerSession session = sessions.get(sessionId);
 
 		if (session == null) {
@@ -327,9 +341,9 @@ private ServerResponse handleMessage(ServerRequest request) {
 
 			// Process the message through the session's handle method
 			session.handle(message).contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext)).block(); // Block
-																														// for
-																														// WebMVC
-																														// compatibility
+			// for
+			// WebMVC
+			// compatibility
 
 			return ServerResponse.ok().build();
 		}
@@ -398,8 +412,8 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 		 * Converts data from one type to another using the configured McpJsonMapper.
 		 * @param data The source data object to convert
 		 * @param typeRef The target type reference
-		 * @return The converted object of type T
 		 * @param  The target type
+		 * @return The converted object of type T
 		 */
 		@Override
 		public  T unmarshalFrom(Object data, TypeRef typeRef) {
diff --git a/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProviderTests.java b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProviderTests.java
new file mode 100644
index 000000000..1074e8a35
--- /dev/null
+++ b/mcp-spring/mcp-spring-webmvc/src/test/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProviderTests.java
@@ -0,0 +1,119 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server.transport;
+
+import io.modelcontextprotocol.client.McpClient;
+import io.modelcontextprotocol.client.transport.HttpClientSseClientTransport;
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.TomcatTestUtil;
+import io.modelcontextprotocol.spec.McpSchema;
+import org.apache.catalina.LifecycleException;
+import org.apache.catalina.LifecycleState;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerResponse;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Integration tests for WebMvcSseServerTransportProvider
+ *
+ * @author lance
+ */
+class WebMvcSseServerTransportProviderTests {
+
+	private static final int PORT = TestUtil.findAvailablePort();
+
+	private static final String CUSTOM_CONTEXT_PATH = "";
+
+	private static final String MESSAGE_ENDPOINT = "/mcp/message";
+
+	private WebMvcSseServerTransportProvider mcpServerTransportProvider;
+
+	McpClient.SyncSpec clientBuilder;
+
+	private TomcatTestUtil.TomcatServer tomcatServer;
+
+	@BeforeEach
+	public void before() {
+		tomcatServer = TomcatTestUtil.createTomcatServer(CUSTOM_CONTEXT_PATH, PORT, TestConfig.class);
+
+		try {
+			tomcatServer.tomcat().start();
+			assertThat(tomcatServer.tomcat().getServer().getState()).isEqualTo(LifecycleState.STARTED);
+		}
+		catch (Exception e) {
+			throw new RuntimeException("Failed to start Tomcat", e);
+		}
+
+		HttpClientSseClientTransport transport = HttpClientSseClientTransport.builder("http://localhost:" + PORT)
+			.sseEndpoint(WebMvcSseServerTransportProvider.DEFAULT_SSE_ENDPOINT)
+			.build();
+
+		clientBuilder = McpClient.sync(transport);
+		mcpServerTransportProvider = tomcatServer.appContext().getBean(WebMvcSseServerTransportProvider.class);
+	}
+
+	@Test
+	void validBaseUrl() {
+		McpServer.async(mcpServerTransportProvider).serverInfo("test-server", "1.0.0").build();
+		try (var client = clientBuilder.clientInfo(new McpSchema.Implementation("Sample " + "client", "0.0.0"))
+			.build()) {
+			assertThat(client.initialize()).isNotNull();
+		}
+	}
+
+	@AfterEach
+	public void after() {
+		if (mcpServerTransportProvider != null) {
+			mcpServerTransportProvider.closeGracefully().block();
+		}
+		if (tomcatServer.appContext() != null) {
+			tomcatServer.appContext().close();
+		}
+		if (tomcatServer.tomcat() != null) {
+			try {
+				tomcatServer.tomcat().stop();
+				tomcatServer.tomcat().destroy();
+			}
+			catch (LifecycleException e) {
+				throw new RuntimeException("Failed to stop Tomcat", e);
+			}
+		}
+	}
+
+	@Configuration
+	@EnableWebMvc
+	static class TestConfig {
+
+		@Bean
+		public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider() {
+
+			return WebMvcSseServerTransportProvider.builder()
+				.baseUrl("http://localhost:" + PORT + "/")
+				.messageEndpoint(MESSAGE_ENDPOINT)
+				.sseEndpoint(WebMvcSseServerTransportProvider.DEFAULT_SSE_ENDPOINT)
+				.jsonMapper(McpJsonMapper.getDefault())
+				.contextExtractor(req -> McpTransportContext.EMPTY)
+				.build();
+		}
+
+		@Bean
+		public RouterFunction routerFunction(WebMvcSseServerTransportProvider transportProvider) {
+			return transportProvider.getRouterFunction();
+		}
+
+	}
+
+}

From c561675e74ac7e7183638e739e7764a704fd5d45 Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Wed, 19 Nov 2025 11:20:12 +0100
Subject: [PATCH 113/125] WebMvcSseServerTransportProvider: do not include
 session ID in SSE event

- This aligns messages with WebFluxSseServerTransportProvider

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../WebMvcSseServerTransportProvider.java     | 76 +++++++------------
 1 file changed, 29 insertions(+), 47 deletions(-)

diff --git a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
index dfaee64b5..6c35de56d 100644
--- a/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
+++ b/mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java
@@ -7,7 +7,6 @@
 import java.io.IOException;
 import java.time.Duration;
 import java.util.List;
-import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
 
@@ -256,39 +255,31 @@ private ServerResponse handleSseConnection(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
 		}
 
-		String sessionId = UUID.randomUUID().toString();
-		logger.debug("Creating new SSE connection for session: {}", sessionId);
-
 		// Send initial endpoint event
-		try {
-			return ServerResponse.sse(sseBuilder -> {
-				sseBuilder.onComplete(() -> {
-					logger.debug("SSE connection completed for session: {}", sessionId);
-					sessions.remove(sessionId);
-				});
-				sseBuilder.onTimeout(() -> {
-					logger.debug("SSE connection timed out for session: {}", sessionId);
-					sessions.remove(sessionId);
-				});
-
-				WebMvcMcpSessionTransport sessionTransport = new WebMvcMcpSessionTransport(sessionId, sseBuilder);
-				McpServerSession session = sessionFactory.create(sessionTransport);
-				this.sessions.put(sessionId, session);
+		return ServerResponse.sse(sseBuilder -> {
+			WebMvcMcpSessionTransport sessionTransport = new WebMvcMcpSessionTransport(sseBuilder);
+			McpServerSession session = sessionFactory.create(sessionTransport);
+			String sessionId = session.getId();
+			logger.debug("Creating new SSE connection for session: {}", sessionId);
+			sseBuilder.onComplete(() -> {
+				logger.debug("SSE connection completed for session: {}", sessionId);
+				sessions.remove(sessionId);
+			});
+			sseBuilder.onTimeout(() -> {
+				logger.debug("SSE connection timed out for session: {}", sessionId);
+				sessions.remove(sessionId);
+			});
+			this.sessions.put(sessionId, session);
 
-				try {
-					sseBuilder.id(sessionId).event(ENDPOINT_EVENT_TYPE).data(buildEndpointUrl(sessionId));
-				}
-				catch (Exception e) {
-					logger.error("Failed to send initial endpoint event: {}", e.getMessage());
-					sseBuilder.error(e);
-				}
-			}, Duration.ZERO);
-		}
-		catch (Exception e) {
-			logger.error("Failed to send initial endpoint event to session {}: {}", sessionId, e.getMessage());
-			sessions.remove(sessionId);
-			return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
-		}
+			try {
+				sseBuilder.event(ENDPOINT_EVENT_TYPE).data(buildEndpointUrl(sessionId));
+			}
+			catch (Exception e) {
+				logger.error("Failed to send initial endpoint event: {}", e.getMessage());
+				this.sessions.remove(sessionId);
+				sseBuilder.error(e);
+			}
+		}, Duration.ZERO);
 	}
 
 	/**
@@ -363,8 +354,6 @@ private ServerResponse handleMessage(ServerRequest request) {
 	 */
 	private class WebMvcMcpSessionTransport implements McpServerTransport {
 
-		private final String sessionId;
-
 		private final SseBuilder sseBuilder;
 
 		/**
@@ -374,14 +363,11 @@ private class WebMvcMcpSessionTransport implements McpServerTransport {
 		private final ReentrantLock sseBuilderLock = new ReentrantLock();
 
 		/**
-		 * Creates a new session transport with the specified ID and SSE builder.
-		 * @param sessionId The unique identifier for this session
+		 * Creates a new session transport with the specified SSE builder.
 		 * @param sseBuilder The SSE builder for sending server events to the client
 		 */
-		WebMvcMcpSessionTransport(String sessionId, SseBuilder sseBuilder) {
-			this.sessionId = sessionId;
+		WebMvcMcpSessionTransport(SseBuilder sseBuilder) {
 			this.sseBuilder = sseBuilder;
-			logger.debug("Session transport {} initialized with SSE builder", sessionId);
 		}
 
 		/**
@@ -395,11 +381,10 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 				sseBuilderLock.lock();
 				try {
 					String jsonText = jsonMapper.writeValueAsString(message);
-					sseBuilder.id(sessionId).event(MESSAGE_EVENT_TYPE).data(jsonText);
-					logger.debug("Message sent to session {}", sessionId);
+					sseBuilder.event(MESSAGE_EVENT_TYPE).data(jsonText);
 				}
 				catch (Exception e) {
-					logger.error("Failed to send message to session {}: {}", sessionId, e.getMessage());
+					logger.error("Failed to send message: {}", e.getMessage());
 					sseBuilder.error(e);
 				}
 				finally {
@@ -427,14 +412,12 @@ public  T unmarshalFrom(Object data, TypeRef typeRef) {
 		@Override
 		public Mono closeGracefully() {
 			return Mono.fromRunnable(() -> {
-				logger.debug("Closing session transport: {}", sessionId);
 				sseBuilderLock.lock();
 				try {
 					sseBuilder.complete();
-					logger.debug("Successfully completed SSE builder for session {}", sessionId);
 				}
 				catch (Exception e) {
-					logger.warn("Failed to complete SSE builder for session {}: {}", sessionId, e.getMessage());
+					logger.warn("Failed to complete SSE builder: {}", e.getMessage());
 				}
 				finally {
 					sseBuilderLock.unlock();
@@ -450,10 +433,9 @@ public void close() {
 			sseBuilderLock.lock();
 			try {
 				sseBuilder.complete();
-				logger.debug("Successfully completed SSE builder for session {}", sessionId);
 			}
 			catch (Exception e) {
-				logger.warn("Failed to complete SSE builder for session {}: {}", sessionId, e.getMessage());
+				logger.warn("Failed to complete SSE builder: {}", e.getMessage());
 			}
 			finally {
 				sseBuilderLock.unlock();

From 7e950ebb6cc3546cc06bbc70ffb03be0c397c1fb Mon Sep 17 00:00:00 2001
From: codeboyzhou 
Date: Fri, 21 Nov 2025 20:44:29 +0800
Subject: [PATCH 114/125] refactor: use builder pattern for CallToolResult and
 Resource (#652)

* use builder pattern for CallToolResult
* use builder pattern for Resource
* simplify lambda expressions in tests
---
 .../server/McpAsyncServer.java                |  17 ++-
 .../server/McpServer.java                     |  30 +++-
 .../server/McpServerFeatures.java             |  21 ++-
 .../server/McpStatelessAsyncServer.java       |  17 ++-
 .../modelcontextprotocol/spec/McpSchema.java  |   3 +-
 .../server/AbstractMcpAsyncServerTests.java   |  89 ++++++++----
 ...stractMcpClientServerIntegrationTests.java |  17 ++-
 .../server/AbstractMcpSyncServerTests.java    | 127 ++++++++++-------
 .../AsyncToolSpecificationBuilderTest.java    |  30 ++--
 .../HttpServletStatelessIntegrationTests.java |   5 +-
 .../SyncToolSpecificationBuilderTest.java     |  16 ++-
 ...stractMcpClientServerIntegrationTests.java |  15 +-
 .../server/AbstractMcpAsyncServerTests.java   |  89 ++++++++----
 .../server/AbstractMcpSyncServerTests.java    | 131 +++++++++++-------
 14 files changed, 405 insertions(+), 202 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
index ac4b36990..23285d514 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java
@@ -24,7 +24,6 @@
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.CompleteResult.CompleteCompletion;
 import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
-import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse;
 import io.modelcontextprotocol.spec.McpSchema.LoggingLevel;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
 import io.modelcontextprotocol.spec.McpSchema.PromptReference;
@@ -398,11 +397,12 @@ public Mono apply(McpAsyncServerExchange exchange, McpSchema.Cal
 				// results that conform to this schema.
 				// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema
 				if (result.structuredContent() == null) {
-					logger.warn(
-							"Response missing structured content which is expected when calling tool with non-empty outputSchema");
-					return new CallToolResult(
-							"Response missing structured content which is expected when calling tool with non-empty outputSchema",
-							true);
+					String content = "Response missing structured content which is expected when calling tool with non-empty outputSchema";
+					logger.warn(content);
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent(content)))
+						.isError(true)
+						.build();
 				}
 
 				// Validate the result against the output schema
@@ -410,7 +410,10 @@ public Mono apply(McpAsyncServerExchange exchange, McpSchema.Cal
 
 				if (!validation.valid()) {
 					logger.warn("Tool call result validation failed: {}", validation.errorMessage());
-					return new CallToolResult(validation.errorMessage(), true);
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent(validation.errorMessage())))
+						.isError(true)
+						.build();
 				}
 
 				if (Utils.isEmpty(result.content())) {
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
index 87c84ba1b..fe3125271 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -67,7 +67,10 @@
  * McpServer.sync(transportProvider)
  *     .serverInfo("my-server", "1.0.0")
  *     .tool(Tool.builder().name("calculator").title("Performs calculations").inputSchema(schema).build(),
- *           (exchange, args) -> new CallToolResult("Result: " + calculate(args)))
+ *           (exchange, args) -> CallToolResult.builder()
+ *                   .content(List.of(new McpSchema.TextContent("Result: " + calculate(args))))
+ *                   .isError(false)
+ *                   .build())
  *     .build();
  * }
  *
@@ -76,7 +79,10 @@
  *     .serverInfo("my-server", "1.0.0")
  *     .tool(Tool.builder().name("calculator").title("Performs calculations").inputSchema(schema).build(),
  *           (exchange, args) -> Mono.fromSupplier(() -> calculate(args))
- *               .map(result -> new CallToolResult("Result: " + result)))
+ *               .map(result -> CallToolResult.builder()
+ *                   .content(List.of(new McpSchema.TextContent("Result: " + result)))
+ *                   .isError(false)
+ *                   .build()))
  *     .build();
  * }
  *
@@ -90,12 +96,18 @@
  *         McpServerFeatures.AsyncToolSpecification.builder()
  * 			.tool(calculatorTool)
  *   	    .callTool((exchange, args) -> Mono.fromSupplier(() -> calculate(args.arguments()))
- *                 .map(result -> new CallToolResult("Result: " + result))))
+ *                 .map(result -> CallToolResult.builder()
+ *                   .content(List.of(new McpSchema.TextContent("Result: " + result)))
+ *                   .isError(false)
+ *                   .build()))
  *.         .build(),
  *         McpServerFeatures.AsyncToolSpecification.builder()
  * 	        .tool((weatherTool)
  *          .callTool((exchange, args) -> Mono.fromSupplier(() -> getWeather(args.arguments()))
- *                 .map(result -> new CallToolResult("Weather: " + result))))
+ *                 .map(result -> CallToolResult.builder()
+ *                   .content(List.of(new McpSchema.TextContent("Weather: " + result)))
+ *                   .isError(false)
+ *                   .build()))
  *          .build()
  *     )
  *     // Register resources
@@ -425,7 +437,10 @@ public AsyncSpecification capabilities(McpSchema.ServerCapabilities serverCap
 		 * .tool(
 		 *     Tool.builder().name("calculator").title("Performs calculations").inputSchema(schema).build(),
 		 *     (exchange, args) -> Mono.fromSupplier(() -> calculate(args))
-		 *         .map(result -> new CallToolResult("Result: " + result))
+		 *         .map(result -> CallToolResult.builder()
+		 *                   .content(List.of(new McpSchema.TextContent("Result: " + result)))
+		 *                   .isError(false)
+		 *                   .build()))
 		 * )
 		 * }
 		 * @param tool The tool definition including name, description, and schema. Must
@@ -1022,7 +1037,10 @@ public SyncSpecification capabilities(McpSchema.ServerCapabilities serverCapa
 		 * Example usage: 
    {@code
 		 * .tool(
 		 *     Tool.builder().name("calculator").title("Performs calculations".inputSchema(schema).build(),
-		 *     (exchange, args) -> new CallToolResult("Result: " + calculate(args))
+		 *     (exchange, args) -> CallToolResult.builder()
+		 *                   .content(List.of(new McpSchema.TextContent("Result: " + calculate(args))))
+		 *                   .isError(false)
+		 *                   .build())
 		 * )
 		 * }
    
 		 * @param tool The tool definition including name, description, and schema. Must
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
index fc5bdfe4e..fe0608b1c 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
@@ -334,7 +334,13 @@ public static Builder builder() {
 	 *
 	 * 
    {@code
 	 * new McpServerFeatures.AsyncResourceSpecification(
-	 * 		new Resource("docs", "Documentation files", "text/markdown"),
+	 *     Resource.builder()
+	 *         .uri("docs")
+	 *         .name("Documentation files")
+	 * 		   .title("Documentation files")
+	 * 		   .mimeType("text/markdown")
+	 * 		   .description("Markdown documentation files")
+	 * 		   .build(),
 	 * 		(exchange, request) -> Mono.fromSupplier(() -> readFile(request.getPath()))
 	 * 				.map(ReadResourceResult::new))
 	 * }
    
@@ -508,7 +514,10 @@ static AsyncCompletionSpecification fromSync(SyncCompletionSpecification complet
 	 * 				.build()
 	 * 		.toolHandler((exchange, req) -> {
 	 * 			String expr = (String) req.arguments().get("expression");
-	 * 			return new CallToolResult("Result: " + evaluate(expr));
+	 * 			return CallToolResult.builder()
+	 *                   .content(List.of(new McpSchema.TextContent("Result: " + evaluate(expr))))
+	 *                   .isError(false)
+	 *                   .build();
 	 * 		}))
 	 *      .build();
 	 * }
@@ -604,7 +613,13 @@ public static Builder builder() {
 	 *
 	 * 
    {@code
 	 * new McpServerFeatures.SyncResourceSpecification(
-	 * 		new Resource("docs", "Documentation files", "text/markdown"),
+	 *     Resource.builder()
+	 *         .uri("docs")
+	 *         .name("Documentation files")
+	 * 		   .title("Documentation files")
+	 * 		   .mimeType("text/markdown")
+	 * 		   .description("Markdown documentation files")
+	 * 		   .build(),
 	 * 		(exchange, request) -> {
 	 * 			String content = readFile(request.getPath());
 	 * 			return new ReadResourceResult(content);
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
index 997df7225..c7a1fd0d7 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java
@@ -14,7 +14,6 @@
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.CompleteResult.CompleteCompletion;
 import io.modelcontextprotocol.spec.McpSchema.ErrorCodes;
-import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse;
 import io.modelcontextprotocol.spec.McpSchema.PromptReference;
 import io.modelcontextprotocol.spec.McpSchema.ResourceReference;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
@@ -277,11 +276,12 @@ public Mono apply(McpTransportContext transportContext, McpSchem
 				// results that conform to this schema.
 				// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema
 				if (result.structuredContent() == null) {
-					logger.warn(
-							"Response missing structured content which is expected when calling tool with non-empty outputSchema");
-					return new CallToolResult(
-							"Response missing structured content which is expected when calling tool with non-empty outputSchema",
-							true);
+					String content = "Response missing structured content which is expected when calling tool with non-empty outputSchema";
+					logger.warn(content);
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent(content)))
+						.isError(true)
+						.build();
 				}
 
 				// Validate the result against the output schema
@@ -289,7 +289,10 @@ public Mono apply(McpTransportContext transportContext, McpSchem
 
 				if (!validation.valid()) {
 					logger.warn("Tool call result validation failed: {}", validation.errorMessage());
-					return new CallToolResult(validation.errorMessage(), true);
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent(validation.errorMessage())))
+						.isError(true)
+						.build();
 				}
 
 				if (Utils.isEmpty(result.content())) {
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 342fc5347..734cff237 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -1562,6 +1562,7 @@ public CallToolResult(List content, Boolean isError, Map meta) {
 			 * @return a new CallToolResult instance
 			 */
 			public CallToolResult build() {
-				return new CallToolResult(content, isError, (Object) structuredContent, meta);
+				return new CallToolResult(content, isError, structuredContent, meta);
 			}
 
 		}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index aa68203dd..090710248 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -7,7 +7,6 @@
 import java.time.Duration;
 import java.util.List;
 
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
@@ -86,7 +85,7 @@ void testGracefulShutdown() {
 	void testImmediateClose() {
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpAsyncServer.close()).doesNotThrowAnyException();
+		assertThatCode(mcpAsyncServer::close).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -104,8 +103,9 @@ void testAddTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		StepVerifier.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(newTool,
-				(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
+		StepVerifier
+			.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(newTool,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))))
 			.verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -125,7 +125,8 @@ void testAddToolCall() {
 
 		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(newTool)
-			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.callHandler((exchange, request) -> Mono
+				.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build())).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -142,11 +143,13 @@ void testAddDuplicateTool() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(duplicateTool, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
+			.tool(duplicateTool,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
-		StepVerifier.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
-				(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
+		StepVerifier
+			.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))))
 			.verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -162,12 +165,15 @@ void testAddDuplicateToolCall() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(duplicateTool,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(duplicateTool)
-			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.callHandler((exchange, request) -> Mono
+				.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build())).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -183,8 +189,12 @@ void testDuplicateToolCallDuringBuilding() {
 
 		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
-			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) // Duplicate!
+			.toolCall(duplicateTool,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
+			.toolCall(duplicateTool,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build())) // Duplicate!
 			.build()).isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Tool with name 'duplicate-build-toolcall' is already registered.");
 	}
@@ -200,11 +210,13 @@ void testDuplicateToolsInBatchListRegistration() {
 		List specs = List.of(
 				McpServerFeatures.AsyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+					.callHandler((exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 					.build(),
 				McpServerFeatures.AsyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+					.callHandler((exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 					.build() // Duplicate!
 		);
 
@@ -227,11 +239,13 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.AsyncToolSpecification.builder()
 				.tool(duplicateTool)
-				.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+				.callHandler((exchange, request) -> Mono
+					.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 				.build(),
 					McpServerFeatures.AsyncToolSpecification.builder()
 						.tool(duplicateTool)
-						.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+						.callHandler((exchange, request) -> Mono
+							.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 						.build() // Duplicate!
 			)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -248,7 +262,9 @@ void testRemoveTool() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(too,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.removeTool(TEST_TOOL_NAME)).verifyComplete();
@@ -277,7 +293,8 @@ void testNotifyToolsListChanged() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(too,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.notifyToolsListChanged()).verifyComplete();
@@ -316,8 +333,13 @@ void testAddResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
@@ -345,8 +367,13 @@ void testAddResourceWithoutCapability() {
 		// Create a server without resource capabilities
 		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
@@ -373,8 +400,13 @@ void testListResources() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
@@ -392,8 +424,13 @@ void testRemoveResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
index 603324631..1f5387f37 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpClientServerIntegrationTests.java
@@ -851,7 +851,7 @@ void testThrowingToolCallIsCaughtBeforeTimeout(String clientType) {
 
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@MethodSource("clientsForTesting")
-	void testToolCallSuccessWithTranportContextExtraction(String clientType) {
+	void testToolCallSuccessWithTransportContextExtraction(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
@@ -1077,7 +1077,10 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 								.logger("test-logger")
 								.data("Another error message")
 								.build()))
-					.thenReturn(new CallToolResult("Logging test completed", false));
+					.thenReturn(CallToolResult.builder()
+							.content(List.of(new McpSchema.TextContent("Logging test completed")))
+							.isError(false)
+							.build());
 					//@formatter:on
 			})
 			.build();
@@ -1172,7 +1175,10 @@ void testProgressNotification(String clientType) throws InterruptedException {
 									0.0, 1.0, "Another processing started")))
 					.then(exchange.progressNotification(
 							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
-					.thenReturn(new CallToolResult(("Progress test completed"), false));
+					.thenReturn(CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent("Progress test completed")))
+						.isError(false)
+						.build());
 			})
 			.build();
 
@@ -1326,7 +1332,10 @@ void testPingSuccess(String clientType) {
 					assertThat(result).isNotNull();
 				}).then(Mono.fromCallable(() -> {
 					executionOrder.set(executionOrder.get() + "3");
-					return new CallToolResult("Async ping test completed", false);
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent("Async ping test completed")))
+						.isError(false)
+						.build();
 				}));
 			})
 			.build();
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 976eb8c2c..915c658e3 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -6,7 +6,6 @@
 
 import java.util.List;
 
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
@@ -78,14 +77,14 @@ void testConstructorWithInvalidArguments() {
 	void testGracefulShutdown() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testImmediateClose() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.close()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::close).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -94,7 +93,7 @@ void testGetAsyncServer() {
 
 		assertThat(mcpSyncServer.getAsyncServer()).isNotNull();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -114,10 +113,10 @@ void testAddTool() {
 			.inputSchema(EMPTY_JSON_SCHEMA)
 			.build();
 		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(newTool,
-				(exchange, args) -> new CallToolResult(List.of(), false))))
+				(exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -134,10 +133,10 @@ void testAddToolCall() {
 
 		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(newTool)
-			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build())).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -151,14 +150,14 @@ void testAddDuplicateTool() {
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(duplicateTool, (exchange, args) -> new CallToolResult(List.of(), false))
+			.tool(duplicateTool, (exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build();
 
 		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
-				(exchange, args) -> new CallToolResult(List.of(), false))))
+				(exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -171,15 +170,16 @@ void testAddDuplicateToolCall() {
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
+			.toolCall(duplicateTool,
+					(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build();
 
 		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(duplicateTool)
-			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build())).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -192,8 +192,10 @@ void testDuplicateToolCallDuringBuilding() {
 
 		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
-			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) // Duplicate!
+			.toolCall(duplicateTool,
+					(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
+			.toolCall(duplicateTool,
+					(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build()) // Duplicate!
 			.build()).isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Tool with name 'duplicate-build-toolcall' is already registered.");
 	}
@@ -208,11 +210,13 @@ void testDuplicateToolsInBatchListRegistration() {
 		List specs = List.of(
 				McpServerFeatures.SyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+					.callHandler(
+							(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 					.build(),
 				McpServerFeatures.SyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+					.callHandler(
+							(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 					.build() // Duplicate!
 		);
 
@@ -235,11 +239,12 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.SyncToolSpecification.builder()
 				.tool(duplicateTool)
-				.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+				.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 				.build(),
 					McpServerFeatures.SyncToolSpecification.builder()
 						.tool(duplicateTool)
-						.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+						.callHandler((exchange,
+								request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 						.build() // Duplicate!
 			)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -256,12 +261,12 @@ void testRemoveTool() {
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(tool, (exchange, args) -> new CallToolResult(List.of(), false))
+			.toolCall(tool, (exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build();
 
 		assertThatCode(() -> mcpSyncServer.removeTool(TEST_TOOL_NAME)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -272,16 +277,16 @@ void testRemoveNonexistentTool() {
 
 		assertThatCode(() -> mcpSyncServer.removeTool("nonexistent-tool")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testNotifyToolsListChanged() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.notifyToolsListChanged()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::notifyToolsListChanged).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -292,9 +297,9 @@ void testNotifyToolsListChanged() {
 	void testNotifyResourcesListChanged() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.notifyResourcesListChanged()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::notifyResourcesListChanged).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -305,7 +310,7 @@ void testNotifyResourcesUpdated() {
 			.notifyResourcesUpdated(new McpSchema.ResourcesUpdatedNotification(TEST_RESOURCE_URI)))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -314,14 +319,18 @@ void testAddResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
 		assertThatCode(() -> mcpSyncServer.addResource(specification)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -334,15 +343,19 @@ void testAddResourceWithNullSpecification() {
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Resource must not be null");
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testAddResourceWithoutCapability() {
 		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
@@ -366,8 +379,12 @@ void testListResources() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
@@ -377,7 +394,7 @@ void testListResources() {
 		assertThat(resources).hasSize(1);
 		assertThat(resources.get(0).uri()).isEqualTo(TEST_RESOURCE_URI);
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -386,15 +403,19 @@ void testRemoveResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
 		mcpSyncServer.addResource(specification);
 		assertThatCode(() -> mcpSyncServer.removeResource(TEST_RESOURCE_URI)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -407,7 +428,7 @@ void testRemoveNonexistentResource() {
 		// as per the new implementation that just logs a warning
 		assertThatCode(() -> mcpSyncServer.removeResource("nonexistent://resource")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -432,7 +453,7 @@ void testAddResourceTemplate() {
 
 		assertThatCode(() -> mcpSyncServer.addResourceTemplate(specification)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -474,7 +495,7 @@ void testRemoveResourceTemplate() {
 
 		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("test://template/{id}")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -496,7 +517,7 @@ void testRemoveNonexistentResourceTemplate() {
 		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("nonexistent://template/{id}"))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -520,7 +541,7 @@ void testListResourceTemplates() {
 
 		assertThat(templates).isNotNull();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -531,9 +552,9 @@ void testListResourceTemplates() {
 	void testNotifyPromptsListChanged() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.notifyPromptsListChanged()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::notifyPromptsListChanged).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -584,7 +605,7 @@ void testRemovePrompt() {
 
 		assertThatCode(() -> mcpSyncServer.removePrompt(TEST_PROMPT_NAME)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -595,7 +616,7 @@ void testRemoveNonexistentPrompt() {
 
 		assertThatCode(() -> mcpSyncServer.removePrompt("nonexistent://template/{id}")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -617,7 +638,7 @@ void testRootsChangeHandlers() {
 			}))
 			.build();
 		assertThat(singleConsumerServer).isNotNull();
-		assertThatCode(() -> singleConsumerServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(singleConsumerServer::closeGracefully).doesNotThrowAnyException();
 		onClose();
 
 		// Test with multiple consumers
@@ -633,7 +654,7 @@ void testRootsChangeHandlers() {
 			.build();
 
 		assertThat(multipleConsumersServer).isNotNull();
-		assertThatCode(() -> multipleConsumersServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(multipleConsumersServer::closeGracefully).doesNotThrowAnyException();
 		onClose();
 
 		// Test error handling
@@ -644,14 +665,14 @@ void testRootsChangeHandlers() {
 			.build();
 
 		assertThat(errorHandlingServer).isNotNull();
-		assertThatCode(() -> errorHandlingServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(errorHandlingServer::closeGracefully).doesNotThrowAnyException();
 		onClose();
 
 		// Test without consumers
 		var noConsumersServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(noConsumersServer).isNotNull();
-		assertThatCode(() -> noConsumersServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(noConsumersServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 }
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
index 8fe8e6fb0..62332fcdb 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/AsyncToolSpecificationBuilderTest.java
@@ -40,7 +40,7 @@ void builderShouldCreateValidAsyncToolSpecification() {
 		McpServerFeatures.AsyncToolSpecification specification = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(tool)
 			.callHandler((exchange, request) -> Mono
-				.just(new CallToolResult(List.of(new TextContent("Test result")), false)))
+				.just(CallToolResult.builder().content(List.of(new TextContent("Test result"))).isError(false).build()))
 			.build();
 
 		assertThat(specification).isNotNull();
@@ -52,7 +52,8 @@ void builderShouldCreateValidAsyncToolSpecification() {
 	@Test
 	void builderShouldThrowExceptionWhenToolIsNull() {
 		assertThatThrownBy(() -> McpServerFeatures.AsyncToolSpecification.builder()
-			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.callHandler((exchange, request) -> Mono
+				.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build()).isInstanceOf(IllegalArgumentException.class).hasMessage("Tool must not be null");
 	}
 
@@ -80,7 +81,8 @@ void builderShouldAllowMethodChaining() {
 
 		// Then - verify method chaining returns the same builder instance
 		assertThat(builder.tool(tool)).isSameAs(builder);
-		assertThat(builder.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false))))
+		assertThat(builder.callHandler(
+				(exchange, request) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build())))
 			.isSameAs(builder);
 	}
 
@@ -96,7 +98,10 @@ void builtSpecificationShouldExecuteCallToolCorrectly() {
 		McpServerFeatures.AsyncToolSpecification specification = McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(tool)
 			.callHandler((exchange, request) -> {
-				return Mono.just(new CallToolResult(List.of(new TextContent(expectedResult)), false));
+				return Mono.just(CallToolResult.builder()
+					.content(List.of(new TextContent(expectedResult)))
+					.isError(false)
+					.build());
 			})
 			.build();
 
@@ -124,8 +129,11 @@ void deprecatedConstructorShouldWorkCorrectly() {
 
 		// Test the deprecated constructor that takes a 'call' function
 		McpServerFeatures.AsyncToolSpecification specification = new McpServerFeatures.AsyncToolSpecification(tool,
-				(exchange, arguments) -> Mono
-					.just(new CallToolResult(List.of(new TextContent(expectedResult)), false)));
+				(exchange,
+						arguments) -> Mono.just(CallToolResult.builder()
+							.content(List.of(new TextContent(expectedResult)))
+							.isError(false)
+							.build()));
 
 		assertThat(specification).isNotNull();
 		assertThat(specification.tool()).isEqualTo(tool);
@@ -169,7 +177,10 @@ void fromSyncShouldConvertSyncToolSpecificationCorrectly() {
 		// Create a sync tool specification
 		McpServerFeatures.SyncToolSpecification syncSpec = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(tool)
-			.callHandler((exchange, request) -> new CallToolResult(List.of(new TextContent(expectedResult)), false))
+			.callHandler((exchange, request) -> CallToolResult.builder()
+				.content(List.of(new TextContent(expectedResult)))
+				.isError(false)
+				.build())
 			.build();
 
 		// Convert to async using fromSync
@@ -209,7 +220,10 @@ void fromSyncShouldConvertSyncToolSpecificationWithDeprecatedCallCorrectly() {
 
 		// Create a sync tool specification using the deprecated constructor
 		McpServerFeatures.SyncToolSpecification syncSpec = new McpServerFeatures.SyncToolSpecification(tool,
-				(exchange, arguments) -> new CallToolResult(List.of(new TextContent(expectedResult)), false));
+				(exchange, arguments) -> CallToolResult.builder()
+					.content(List.of(new TextContent(expectedResult)))
+					.isError(false)
+					.build());
 
 		// Convert to async using fromSync
 		McpServerFeatures.AsyncToolSpecification asyncSpec = McpServerFeatures.AsyncToolSpecification
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
index de74bafc1..491c2d4ed 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/HttpServletStatelessIntegrationTests.java
@@ -114,7 +114,10 @@ void testToolCallSuccess(String clientType) {
 
 		var clientBuilder = clientBuilders.get(clientType);
 
-		var callResponse = new CallToolResult(List.of(new McpSchema.TextContent("CALL RESPONSE")), null);
+		var callResponse = CallToolResult.builder()
+			.content(List.of(new McpSchema.TextContent("CALL RESPONSE")))
+			.isError(false)
+			.build();
 		McpStatelessServerFeatures.SyncToolSpecification tool1 = new McpStatelessServerFeatures.SyncToolSpecification(
 				Tool.builder().name("tool1").title("tool1 description").inputSchema(EMPTY_JSON_SCHEMA).build(),
 				(transportContext, request) -> {
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
index cd643c600..9bcd2bc84 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/SyncToolSpecificationBuilderTest.java
@@ -32,7 +32,10 @@ void builderShouldCreateValidSyncToolSpecification() {
 
 		McpServerFeatures.SyncToolSpecification specification = McpServerFeatures.SyncToolSpecification.builder()
 			.tool(tool)
-			.callHandler((exchange, request) -> new CallToolResult(List.of(new TextContent("Test result")), false))
+			.callHandler((exchange, request) -> CallToolResult.builder()
+				.content(List.of(new TextContent("Test result")))
+				.isError(false)
+				.build())
 			.build();
 
 		assertThat(specification).isNotNull();
@@ -44,7 +47,7 @@ void builderShouldCreateValidSyncToolSpecification() {
 	@Test
 	void builderShouldThrowExceptionWhenToolIsNull() {
 		assertThatThrownBy(() -> McpServerFeatures.SyncToolSpecification.builder()
-			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build()).isInstanceOf(IllegalArgumentException.class).hasMessage("Tool must not be null");
 	}
 
@@ -64,7 +67,9 @@ void builderShouldAllowMethodChaining() {
 
 		// Then - verify method chaining returns the same builder instance
 		assertThat(builder.tool(tool)).isSameAs(builder);
-		assertThat(builder.callHandler((exchange, request) -> new CallToolResult(List.of(), false))).isSameAs(builder);
+		assertThat(builder
+			.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build()))
+			.isSameAs(builder);
 	}
 
 	@Test
@@ -80,7 +85,10 @@ void builtSpecificationShouldExecuteCallToolCorrectly() {
 			.tool(tool)
 			.callHandler((exchange, request) -> {
 				// Simple test implementation
-				return new CallToolResult(List.of(new TextContent(expectedResult)), false);
+				return CallToolResult.builder()
+					.content(List.of(new TextContent(expectedResult)))
+					.isError(false)
+					.build();
 			})
 			.build();
 
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
index 37a1ef31d..270bc4308 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/AbstractMcpClientServerIntegrationTests.java
@@ -1081,7 +1081,10 @@ void testLoggingNotification(String clientType) throws InterruptedException {
 								.logger("test-logger")
 								.data("Another error message")
 								.build()))
-					.thenReturn(new CallToolResult("Logging test completed", false));
+					.thenReturn(CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent("Logging test completed")))
+						.isError(false)
+						.build());
 					//@formatter:on
 			})
 			.build();
@@ -1176,7 +1179,10 @@ void testProgressNotification(String clientType) throws InterruptedException {
 									0.0, 1.0, "Another processing started")))
 					.then(exchange.progressNotification(
 							new McpSchema.ProgressNotification(progressToken, 1.0, 1.0, "Processing completed")))
-					.thenReturn(new CallToolResult(("Progress test completed"), false));
+					.thenReturn(CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent("Progress test completed")))
+						.isError(false)
+						.build());
 			})
 			.build();
 
@@ -1330,7 +1336,10 @@ void testPingSuccess(String clientType) {
 					assertThat(result).isNotNull();
 				}).then(Mono.fromCallable(() -> {
 					executionOrder.set(executionOrder.get() + "3");
-					return new CallToolResult("Async ping test completed", false);
+					return CallToolResult.builder()
+						.content(List.of(new McpSchema.TextContent("Async ping test completed")))
+						.isError(false)
+						.build();
 				}));
 			})
 			.build();
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
index c24bcd622..d6677ec9a 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java
@@ -7,7 +7,6 @@
 import java.time.Duration;
 import java.util.List;
 
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
@@ -90,7 +89,7 @@ void testGracefulShutdown() {
 	void testImmediateClose() {
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpAsyncServer.close()).doesNotThrowAnyException();
+		assertThatCode(mcpAsyncServer::close).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -108,8 +107,9 @@ void testAddTool() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.build();
 
-		StepVerifier.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(newTool,
-				(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
+		StepVerifier
+			.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(newTool,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))))
 			.verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -129,7 +129,8 @@ void testAddToolCall() {
 
 		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(newTool)
-			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.callHandler((exchange, request) -> Mono
+				.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build())).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -146,11 +147,13 @@ void testAddDuplicateTool() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(duplicateTool, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
+			.tool(duplicateTool,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
-		StepVerifier.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
-				(exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))))
+		StepVerifier
+			.create(mcpAsyncServer.addTool(new McpServerFeatures.AsyncToolSpecification(duplicateTool,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))))
 			.verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -166,12 +169,15 @@ void testAddDuplicateToolCall() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(duplicateTool,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.addTool(McpServerFeatures.AsyncToolSpecification.builder()
 			.tool(duplicateTool)
-			.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.callHandler((exchange, request) -> Mono
+				.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build())).verifyComplete();
 
 		assertThatCode(() -> mcpAsyncServer.closeGracefully().block(Duration.ofSeconds(10))).doesNotThrowAnyException();
@@ -187,8 +193,12 @@ void testDuplicateToolCallDuringBuilding() {
 
 		assertThatThrownBy(() -> prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
-			.toolCall(duplicateTool, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false))) // Duplicate!
+			.toolCall(duplicateTool,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
+			.toolCall(duplicateTool,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build())) // Duplicate!
 			.build()).isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Tool with name 'duplicate-build-toolcall' is already registered.");
 	}
@@ -204,11 +214,13 @@ void testDuplicateToolsInBatchListRegistration() {
 		List specs = List.of(
 				McpServerFeatures.AsyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+					.callHandler((exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 					.build(),
 				McpServerFeatures.AsyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+					.callHandler((exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 					.build() // Duplicate!
 		);
 
@@ -231,11 +243,13 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.AsyncToolSpecification.builder()
 				.tool(duplicateTool)
-				.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+				.callHandler((exchange, request) -> Mono
+					.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 				.build(),
 					McpServerFeatures.AsyncToolSpecification.builder()
 						.tool(duplicateTool)
-						.callHandler((exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+						.callHandler((exchange, request) -> Mono
+							.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 						.build() // Duplicate!
 			)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -252,7 +266,9 @@ void testRemoveTool() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(too,
+					(exchange, request) -> Mono
+						.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.removeTool(TEST_TOOL_NAME)).verifyComplete();
@@ -281,7 +297,8 @@ void testNotifyToolsListChanged() {
 
 		var mcpAsyncServer = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(too,
+					(exchange, args) -> Mono.just(CallToolResult.builder().content(List.of()).isError(false).build()))
 			.build();
 
 		StepVerifier.create(mcpAsyncServer.notifyToolsListChanged()).verifyComplete();
@@ -320,8 +337,13 @@ void testAddResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
@@ -349,8 +371,13 @@ void testAddResourceWithoutCapability() {
 		// Create a server without resource capabilities
 		McpAsyncServer serverWithoutResources = prepareAsyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
@@ -377,8 +404,13 @@ void testListResources() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
@@ -396,8 +428,13 @@ void testRemoveResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.AsyncResourceSpecification specification = new McpServerFeatures.AsyncResourceSpecification(
 				resource, (exchange, req) -> Mono.just(new ReadResourceResult(List.of())));
 
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
index 591f750cb..0a59d0aae 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java
@@ -6,7 +6,6 @@
 
 import java.util.List;
 
-import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
@@ -77,14 +76,14 @@ void testConstructorWithInvalidArguments() {
 	void testGracefulShutdown() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testImmediateClose() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.close()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::close).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -93,7 +92,7 @@ void testGetAsyncServer() {
 
 		assertThat(mcpSyncServer.getAsyncServer()).isNotNull();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -113,10 +112,10 @@ void testAddTool() {
 			.inputSchema(EMPTY_JSON_SCHEMA)
 			.build();
 		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(newTool,
-				(exchange, args) -> new CallToolResult(List.of(), false))))
+				(exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -133,10 +132,10 @@ void testAddToolCall() {
 
 		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(newTool)
-			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build())).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -150,14 +149,14 @@ void testAddDuplicateTool() {
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(duplicateTool, (exchange, args) -> new CallToolResult(List.of(), false))
+			.tool(duplicateTool, (exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build();
 
 		assertThatCode(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
-				(exchange, args) -> new CallToolResult(List.of(), false))))
+				(exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -170,15 +169,16 @@ void testAddDuplicateToolCall() {
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
+			.toolCall(duplicateTool,
+					(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build();
 
 		assertThatCode(() -> mcpSyncServer.addTool(McpServerFeatures.SyncToolSpecification.builder()
 			.tool(duplicateTool)
-			.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+			.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build())).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -191,8 +191,10 @@ void testDuplicateToolCallDuringBuilding() {
 
 		assertThatThrownBy(() -> prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false))
-			.toolCall(duplicateTool, (exchange, request) -> new CallToolResult(List.of(), false)) // Duplicate!
+			.toolCall(duplicateTool,
+					(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
+			.toolCall(duplicateTool,
+					(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build()) // Duplicate!
 			.build()).isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Tool with name 'duplicate-build-toolcall' is already registered.");
 	}
@@ -207,11 +209,13 @@ void testDuplicateToolsInBatchListRegistration() {
 		List specs = List.of(
 				McpServerFeatures.SyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+					.callHandler(
+							(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 					.build(),
 				McpServerFeatures.SyncToolSpecification.builder()
 					.tool(duplicateTool)
-					.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+					.callHandler(
+							(exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 					.build() // Duplicate!
 		);
 
@@ -234,11 +238,12 @@ void testDuplicateToolsInBatchVarargsRegistration() {
 			.capabilities(ServerCapabilities.builder().tools(true).build())
 			.tools(McpServerFeatures.SyncToolSpecification.builder()
 				.tool(duplicateTool)
-				.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+				.callHandler((exchange, request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 				.build(),
 					McpServerFeatures.SyncToolSpecification.builder()
 						.tool(duplicateTool)
-						.callHandler((exchange, request) -> new CallToolResult(List.of(), false))
+						.callHandler((exchange,
+								request) -> CallToolResult.builder().content(List.of()).isError(false).build())
 						.build() // Duplicate!
 			)
 			.build()).isInstanceOf(IllegalArgumentException.class)
@@ -255,12 +260,12 @@ void testRemoveTool() {
 
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.toolCall(tool, (exchange, args) -> new CallToolResult(List.of(), false))
+			.toolCall(tool, (exchange, args) -> CallToolResult.builder().content(List.of()).isError(false).build())
 			.build();
 
 		assertThatCode(() -> mcpSyncServer.removeTool(TEST_TOOL_NAME)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -271,16 +276,16 @@ void testRemoveNonexistentTool() {
 
 		assertThatCode(() -> mcpSyncServer.removeTool("nonexistent-tool")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testNotifyToolsListChanged() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.notifyToolsListChanged()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::notifyToolsListChanged).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -291,9 +296,9 @@ void testNotifyToolsListChanged() {
 	void testNotifyResourcesListChanged() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.notifyResourcesListChanged()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::notifyResourcesListChanged).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -304,7 +309,7 @@ void testNotifyResourcesUpdated() {
 			.notifyResourcesUpdated(new McpSchema.ResourcesUpdatedNotification(TEST_RESOURCE_URI)))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -313,14 +318,19 @@ void testAddResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
 		assertThatCode(() -> mcpSyncServer.addResource(specification)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -333,15 +343,20 @@ void testAddResourceWithNullSpecification() {
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Resource must not be null");
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
 	void testAddResourceWithoutCapability() {
 		var serverWithoutResources = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
@@ -365,8 +380,13 @@ void testListResources() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
@@ -376,7 +396,7 @@ void testListResources() {
 		assertThat(resources).hasSize(1);
 		assertThat(resources.get(0).uri()).isEqualTo(TEST_RESOURCE_URI);
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -385,15 +405,20 @@ void testRemoveResource() {
 			.capabilities(ServerCapabilities.builder().resources(true, false).build())
 			.build();
 
-		Resource resource = new Resource(TEST_RESOURCE_URI, "Test Resource", "text/plain", "Test resource description",
-				null);
+		Resource resource = Resource.builder()
+			.uri(TEST_RESOURCE_URI)
+			.name("Test Resource")
+			.title("Test Resource")
+			.mimeType("text/plain")
+			.description("Test resource description")
+			.build();
 		McpServerFeatures.SyncResourceSpecification specification = new McpServerFeatures.SyncResourceSpecification(
 				resource, (exchange, req) -> new ReadResourceResult(List.of()));
 
 		mcpSyncServer.addResource(specification);
 		assertThatCode(() -> mcpSyncServer.removeResource(TEST_RESOURCE_URI)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -406,7 +431,7 @@ void testRemoveNonexistentResource() {
 		// as per the new implementation that just logs a warning
 		assertThatCode(() -> mcpSyncServer.removeResource("nonexistent://resource")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -431,7 +456,7 @@ void testAddResourceTemplate() {
 
 		assertThatCode(() -> mcpSyncServer.addResourceTemplate(specification)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -473,7 +498,7 @@ void testRemoveResourceTemplate() {
 
 		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("test://template/{id}")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -495,7 +520,7 @@ void testRemoveNonexistentResourceTemplate() {
 		assertThatCode(() -> mcpSyncServer.removeResourceTemplate("nonexistent://template/{id}"))
 			.doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -519,7 +544,7 @@ void testListResourceTemplates() {
 
 		assertThat(templates).isNotNull();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -530,9 +555,9 @@ void testListResourceTemplates() {
 	void testNotifyPromptsListChanged() {
 		var mcpSyncServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
-		assertThatCode(() -> mcpSyncServer.notifyPromptsListChanged()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::notifyPromptsListChanged).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -583,7 +608,7 @@ void testRemovePrompt() {
 
 		assertThatCode(() -> mcpSyncServer.removePrompt(TEST_PROMPT_NAME)).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	@Test
@@ -594,7 +619,7 @@ void testRemoveNonexistentPrompt() {
 
 		assertThatCode(() -> mcpSyncServer.removePrompt("nonexistent://template/{id}")).doesNotThrowAnyException();
 
-		assertThatCode(() -> mcpSyncServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(mcpSyncServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 	// ---------------------------------------
@@ -616,7 +641,7 @@ void testRootsChangeHandlers() {
 			}))
 			.build();
 		assertThat(singleConsumerServer).isNotNull();
-		assertThatCode(() -> singleConsumerServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(singleConsumerServer::closeGracefully).doesNotThrowAnyException();
 		onClose();
 
 		// Test with multiple consumers
@@ -632,7 +657,7 @@ void testRootsChangeHandlers() {
 			.build();
 
 		assertThat(multipleConsumersServer).isNotNull();
-		assertThatCode(() -> multipleConsumersServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(multipleConsumersServer::closeGracefully).doesNotThrowAnyException();
 		onClose();
 
 		// Test error handling
@@ -643,14 +668,14 @@ void testRootsChangeHandlers() {
 			.build();
 
 		assertThat(errorHandlingServer).isNotNull();
-		assertThatCode(() -> errorHandlingServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(errorHandlingServer::closeGracefully).doesNotThrowAnyException();
 		onClose();
 
 		// Test without consumers
 		var noConsumersServer = prepareSyncServerBuilder().serverInfo("test-server", "1.0.0").build();
 
 		assertThat(noConsumersServer).isNotNull();
-		assertThatCode(() -> noConsumersServer.closeGracefully()).doesNotThrowAnyException();
+		assertThatCode(noConsumersServer::closeGracefully).doesNotThrowAnyException();
 	}
 
 }

From e6045f7287667c065e26fa276d48ae8af03b3333 Mon Sep 17 00:00:00 2001
From: Daniel Garnier-Moiroux 
Date: Thu, 20 Nov 2025 15:50:46 +0100
Subject: [PATCH 115/125] Basic version negotiation capabilities

- We do not support full version negotiation, but this commit allows the
  client to the send the correct version to match that of the server.
- There is one limitation: the GET /mcp request happens too early,
  before we have deserialized the initialization response, so we do not
  know the negotiated version yet. This request will have the client
  latest version as Mcp-Protocol-Version value.

Signed-off-by: Daniel Garnier-Moiroux 
---
 .../client/LifecycleInitializer.java            |  6 +++++-
 .../client/McpAsyncClient.java                  |  2 ++
 .../HttpClientStreamableHttpTransport.java      | 13 ++++++++++---
 .../spec/McpTransportSession.java               |  4 ++--
 ...eHttpVersionNegotiationIntegrationTests.java | 16 +++++++++-------
 .../McpTestRequestRecordingServletFilter.java   |  4 ++--
 .../WebClientStreamableHttpTransport.java       | 13 +++++++++----
 ...eHttpVersionNegotiationIntegrationTests.java | 17 +++++++++++------
 ...tRequestRecordingExchangeFilterFunction.java |  5 +++--
 9 files changed, 53 insertions(+), 27 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
index f56c79a6d..07d86f40e 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java
@@ -287,7 +287,9 @@ public  Mono withInitialization(String actionName, Function operation.apply(res)
+					.contextWrite(c -> c.put(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION,
+							res.initializeResult().protocolVersion())));
 		});
 	}
 
@@ -319,6 +321,8 @@ private Mono doInitialize(DefaultInitialization init
 			}
 
 			return mcpClientSession.sendNotification(McpSchema.METHOD_NOTIFICATION_INITIALIZED, null)
+				.contextWrite(
+						c -> c.put(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION, initializeResult.protocolVersion()))
 				.thenReturn(initializeResult);
 		}).flatMap(initializeResult -> {
 			initialization.cacheResult(initializeResult);
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
index 2d1f4b43c..e6a09cd08 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java
@@ -106,6 +106,8 @@ public class McpAsyncClient {
 	public static final TypeRef PROGRESS_NOTIFICATION_TYPE_REF = new TypeRef<>() {
 	};
 
+	public static final String NEGOTIATED_PROTOCOL_VERSION = "io.modelcontextprotocol.client.negotiated-protocol-version";
+
 	/**
 	 * Client capabilities.
 	 */
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 c48aedbcf..e41f45ebb 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
@@ -20,6 +20,7 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+import io.modelcontextprotocol.client.McpAsyncClient;
 import io.modelcontextprotocol.client.transport.ResponseSubscribers.ResponseEvent;
 import io.modelcontextprotocol.client.transport.customizer.McpAsyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
@@ -193,7 +194,9 @@ private Publisher createDelete(String sessionId) {
 				.uri(uri)
 				.header("Cache-Control", "no-cache")
 				.header(HttpHeaders.MCP_SESSION_ID, sessionId)
-				.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
+				.header(HttpHeaders.PROTOCOL_VERSION,
+						ctx.getOrDefault(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION,
+								this.latestSupportedProtocolVersion))
 				.DELETE();
 			var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
 			return Mono.from(this.httpRequestCustomizer.customize(builder, "DELETE", uri, null, transportContext));
@@ -264,7 +267,9 @@ private Mono reconnect(McpTransportStream stream) {
 				var builder = requestBuilder.uri(uri)
 					.header(HttpHeaders.ACCEPT, TEXT_EVENT_STREAM)
 					.header("Cache-Control", "no-cache")
-					.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
+					.header(HttpHeaders.PROTOCOL_VERSION,
+							connectionCtx.getOrDefault(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION,
+									this.latestSupportedProtocolVersion))
 					.GET();
 				var transportContext = connectionCtx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
 				return Mono.from(this.httpRequestCustomizer.customize(builder, "GET", uri, null, transportContext));
@@ -439,7 +444,9 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 					.header(HttpHeaders.ACCEPT, APPLICATION_JSON + ", " + TEXT_EVENT_STREAM)
 					.header(HttpHeaders.CONTENT_TYPE, APPLICATION_JSON)
 					.header(HttpHeaders.CACHE_CONTROL, "no-cache")
-					.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
+					.header(HttpHeaders.PROTOCOL_VERSION,
+							ctx.getOrDefault(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION,
+									this.latestSupportedProtocolVersion))
 					.POST(HttpRequest.BodyPublishers.ofString(jsonBody));
 				var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
 				return Mono
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
index 716ff0d16..68f0fc5bb 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransportSession.java
@@ -4,10 +4,10 @@
 
 package io.modelcontextprotocol.spec;
 
-import org.reactivestreams.Publisher;
-
 import java.util.Optional;
 
+import org.reactivestreams.Publisher;
+
 /**
  * An abstraction of the session as perceived from the MCP transport layer. Not to be
  * confused with the {@link McpSession} type that operates at the level of the JSON-RPC
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java
index 12a3ef9c6..8efb6a960 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/common/HttpClientStreamableHttpVersionNegotiationIntegrationTests.java
@@ -89,7 +89,7 @@ void usesLatestVersion() {
 	}
 
 	@Test
-	void usesCustomLatestVersion() {
+	void usesServerSupportedVersion() {
 		startTomcat();
 
 		var transport = HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
@@ -101,19 +101,21 @@ void usesCustomLatestVersion() {
 		McpSchema.CallToolResult response = client.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
 
 		var calls = requestRecordingFilter.getCalls();
-
-		assertThat(calls).filteredOn(c -> !c.body().contains("\"method\":\"initialize\""))
-			// GET /mcp ; POST notification/initialized ; POST tools/call
-			.hasSize(3)
+		// Initialize tells the server the Client's latest supported version
+		// FIXME: Set the correct protocol version on GET /mcp
+		assertThat(calls).filteredOn(c -> c.method().equals("POST") && !c.body().contains("\"method\":\"initialize\""))
+			// POST notification/initialized ; POST tools/call
+			.hasSize(2)
 			.map(McpTestRequestRecordingServletFilter.Call::headers)
-			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version", "2263-03-18"));
+			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version",
+					ProtocolVersions.MCP_2025_06_18));
 
 		assertThat(response).isNotNull();
 		assertThat(response.content()).hasSize(1)
 			.first()
 			.extracting(McpSchema.TextContent.class::cast)
 			.extracting(McpSchema.TextContent::text)
-			.isEqualTo("2263-03-18");
+			.isEqualTo(ProtocolVersions.MCP_2025_06_18);
 		mcpServer.close();
 	}
 
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java
index 09f0d305d..b94552d12 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/server/transport/McpTestRequestRecordingServletFilter.java
@@ -46,7 +46,7 @@ public void doFilter(ServletRequest servletRequest, ServletResponse servletRespo
 				.collect(Collectors.toUnmodifiableMap(Function.identity(),
 						name -> String.join(",", Collections.list(req.getHeaders(name)))));
 			var request = new CachedBodyHttpServletRequest(req);
-			calls.add(new Call(headers, request.getBodyAsString()));
+			calls.add(new Call(req.getMethod(), headers, request.getBodyAsString()));
 			filterChain.doFilter(request, servletResponse);
 		}
 		else {
@@ -60,7 +60,7 @@ public List getCalls() {
 		return List.copyOf(calls);
 	}
 
-	public record Call(Map headers, String body) {
+	public record Call(String method, Map headers, String body) {
 
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index 6b1d6ba8a..f0d3ad839 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -24,6 +24,7 @@
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.client.WebClientResponseException;
 
+import io.modelcontextprotocol.client.McpAsyncClient;
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.ClosedMcpTransportSession;
@@ -225,7 +226,9 @@ private Mono reconnect(McpTransportStream stream) {
 			Disposable connection = webClient.get()
 				.uri(this.endpoint)
 				.accept(MediaType.TEXT_EVENT_STREAM)
-				.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
+				.header(HttpHeaders.PROTOCOL_VERSION,
+						ctx.getOrDefault(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION,
+								this.latestSupportedProtocolVersion))
 				.headers(httpHeaders -> {
 					transportSession.sessionId().ifPresent(id -> httpHeaders.add(HttpHeaders.MCP_SESSION_ID, id));
 					if (stream != null) {
@@ -288,10 +291,12 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 			final AtomicReference disposableRef = new AtomicReference<>();
 			final McpTransportSession transportSession = this.activeSession.get();
 
-			Disposable connection = webClient.post()
+			Disposable connection = Flux.deferContextual(ctx -> webClient.post()
 				.uri(this.endpoint)
 				.accept(MediaType.APPLICATION_JSON, MediaType.TEXT_EVENT_STREAM)
-				.header(HttpHeaders.PROTOCOL_VERSION, this.latestSupportedProtocolVersion)
+				.header(HttpHeaders.PROTOCOL_VERSION,
+						ctx.getOrDefault(McpAsyncClient.NEGOTIATED_PROTOCOL_VERSION,
+								this.latestSupportedProtocolVersion))
 				.headers(httpHeaders -> {
 					transportSession.sessionId().ifPresent(id -> httpHeaders.add(HttpHeaders.MCP_SESSION_ID, id));
 				})
@@ -350,7 +355,7 @@ else if (mediaType.isCompatibleWith(MediaType.APPLICATION_JSON)) {
 						}
 						return this.extractError(response, sessionRepresentation);
 					}
-				})
+				}))
 				.flatMap(jsonRpcMessage -> this.handler.get().apply(Mono.just(jsonRpcMessage)))
 				.onErrorComplete(t -> {
 					// handle the error first
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java
index 7627bd419..5d2bfda68 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxStreamableHttpVersionNegotiationIntegrationTests.java
@@ -27,6 +27,7 @@
 import reactor.netty.DisposableServer;
 import reactor.netty.http.server.HttpServer;
 
+import org.springframework.http.HttpMethod;
 import org.springframework.http.server.reactive.HttpHandler;
 import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -116,7 +117,7 @@ void usesLatestVersion() {
 	}
 
 	@Test
-	void usesCustomLatestVersion() {
+	void usesServerSupportedVersion() {
 		var transport = WebClientStreamableHttpTransport
 			.builder(WebClient.builder().baseUrl("http://localhost:" + PORT))
 			.supportedProtocolVersions(List.of(ProtocolVersions.MCP_2025_06_18, "2263-03-18"))
@@ -128,18 +129,22 @@ void usesCustomLatestVersion() {
 		McpSchema.CallToolResult response = client.callTool(new McpSchema.CallToolRequest("test-tool", Map.of()));
 
 		var calls = recordingFilterFunction.getCalls();
-		assertThat(calls).filteredOn(c -> !c.body().contains("\"method\":\"initialize\""))
-			// GET /mcp ; POST notification/initialized ; POST tools/call
-			.hasSize(3)
+		// Initialize tells the server the Client's latest supported version
+		// FIXME: Set the correct protocol version on GET /mcp
+		assertThat(calls)
+			.filteredOn(c -> !c.body().contains("\"method\":\"initialize\"") && c.method().equals(HttpMethod.POST))
+			// POST notification/initialized ; POST tools/call
+			.hasSize(2)
 			.map(McpTestRequestRecordingExchangeFilterFunction.Call::headers)
-			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version", "2263-03-18"));
+			.allSatisfy(headers -> assertThat(headers).containsEntry("mcp-protocol-version",
+					ProtocolVersions.MCP_2025_06_18));
 
 		assertThat(response).isNotNull();
 		assertThat(response.content()).hasSize(1)
 			.first()
 			.extracting(McpSchema.TextContent.class::cast)
 			.extracting(McpSchema.TextContent::text)
-			.isEqualTo("2263-03-18");
+			.isEqualTo(ProtocolVersions.MCP_2025_06_18);
 		mcpServer.close();
 	}
 
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java
index 5600795c1..55129d481 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/utils/McpTestRequestRecordingExchangeFilterFunction.java
@@ -11,6 +11,7 @@
 
 import reactor.core.publisher.Mono;
 
+import org.springframework.http.HttpMethod;
 import org.springframework.web.reactive.function.server.HandlerFilterFunction;
 import org.springframework.web.reactive.function.server.HandlerFunction;
 import org.springframework.web.reactive.function.server.ServerRequest;
@@ -34,7 +35,7 @@ public Mono filter(ServerRequest request, HandlerFunction next)
 			.collect(Collectors.toMap(String::toLowerCase, k -> String.join(",", request.headers().header(k))));
 
 		var cr = request.bodyToMono(String.class).defaultIfEmpty("").map(body -> {
-			this.calls.add(new Call(headers, body));
+			this.calls.add(new Call(request.method(), headers, body));
 			return ServerRequest.from(request).body(body).build();
 		});
 
@@ -46,7 +47,7 @@ public List getCalls() {
 		return List.copyOf(calls);
 	}
 
-	public record Call(Map headers, String body) {
+	public record Call(HttpMethod method, Map headers, String body) {
 
 	}
 

From 06fdc71ef222c6fb72dd5bbe5cc20be92cae73e8 Mon Sep 17 00:00:00 2001
From: Christian Tzolov <1351573+tzolov@users.noreply.github.com>
Date: Fri, 28 Nov 2025 13:35:10 +0100
Subject: [PATCH 116/125] Revert "WebClientStreamableHttpTransport: use
 Spring-5 compatible methods (#649)" (#696)

This reverts commit 67f8eabb7a0ab70b43b5223768b3aaafd243c843.
---
 .../WebClientStreamableHttpTransport.java     | 49 +++++--------------
 1 file changed, 12 insertions(+), 37 deletions(-)

diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index f0d3ad839..a8a4762c2 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -313,7 +313,7 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 
 					// The spec mentions only ACCEPTED, but the existing SDKs can return
 					// 200 OK for notifications
-					if (is2xx(response)) {
+					if (response.statusCode().is2xxSuccessful()) {
 						Optional contentType = response.headers().contentType();
 						long contentLength = response.headers().contentLength().orElse(-1);
 						// Existing SDKs consume notifications with no response body nor
@@ -397,15 +397,14 @@ private Flux extractError(ClientResponse response, Str
 			}
 			catch (IOException ex) {
 				toPropagate = new McpTransportException("Sending request failed, " + e.getMessage(), e);
-				logger.debug("Received content together with {} HTTP code response: {}", response.rawStatusCode(),
-						body);
+				logger.debug("Received content together with {} HTTP code response: {}", response.statusCode(), body);
 			}
 
 			// Some implementations can return 400 when presented with a
 			// session id that it doesn't know about, so we will
 			// invalidate the session
 			// https://github.com/modelcontextprotocol/typescript-sdk/issues/389
-			if (isBadRequest(responseException)) {
+			if (responseException.getStatusCode().isSameCodeAs(HttpStatus.BAD_REQUEST)) {
 				if (!sessionRepresentation.equals(MISSING_SESSION_ID)) {
 					return Mono.error(new McpTransportSessionNotFoundException(sessionRepresentation, toPropagate));
 				}
@@ -425,8 +424,16 @@ private Flux eventStream(McpTransportStream= 200 && response.rawStatusCode() < 300;
-	}
-
 }

From 082444e18f1cb9269bcc7a3ecb6ec860e0159d1b Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 4 Dec 2025 15:57:27 +0100
Subject: [PATCH 117/125] Next development version

Signed-off-by: Christian Tzolov 
---
 mcp-bom/pom.xml                       |  2 +-
 mcp-core/pom.xml                      |  6 +++---
 mcp-json-jackson2/pom.xml             |  4 ++--
 mcp-json/pom.xml                      |  2 +-
 mcp-spring/mcp-spring-webflux/pom.xml |  8 ++++----
 mcp-spring/mcp-spring-webmvc/pom.xml  | 10 +++++-----
 mcp-test/pom.xml                      |  4 ++--
 mcp/pom.xml                           |  6 +++---
 pom.xml                               |  2 +-
 9 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml
index b06baea81..447c9e0bd 100644
--- a/mcp-bom/pom.xml
+++ b/mcp-bom/pom.xml
@@ -7,7 +7,7 @@
     
         io.modelcontextprotocol.sdk
         mcp-parent
-        0.17.0-SNAPSHOT
+        0.18.0-SNAPSHOT
     
 
     mcp-bom
diff --git a/mcp-core/pom.xml b/mcp-core/pom.xml
index 39b4c9dc7..9e23ffd79 100644
--- a/mcp-core/pom.xml
+++ b/mcp-core/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.17.0-SNAPSHOT
+		0.18.0-SNAPSHOT
 	
 	mcp-core
 	jar
@@ -68,7 +68,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.17.0-SNAPSHOT
+            0.18.0-SNAPSHOT
         
 
 		
@@ -101,7 +101,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.17.0-SNAPSHOT
+            0.18.0-SNAPSHOT
             test
         
 
diff --git a/mcp-json-jackson2/pom.xml b/mcp-json-jackson2/pom.xml
index 8ea1fa7d2..de2ac58ce 100644
--- a/mcp-json-jackson2/pom.xml
+++ b/mcp-json-jackson2/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.17.0-SNAPSHOT
+		0.18.0-SNAPSHOT
 	
 	mcp-json-jackson2
 	jar
@@ -37,7 +37,7 @@
         
             io.modelcontextprotocol.sdk
             mcp-json
-            0.17.0-SNAPSHOT
+            0.18.0-SNAPSHOT
         
         
             com.fasterxml.jackson.core
diff --git a/mcp-json/pom.xml b/mcp-json/pom.xml
index 9fc850e11..2cbcf3516 100644
--- a/mcp-json/pom.xml
+++ b/mcp-json/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.17.0-SNAPSHOT
+		0.18.0-SNAPSHOT
 	
 	mcp-json
 	jar
diff --git a/mcp-spring/mcp-spring-webflux/pom.xml b/mcp-spring/mcp-spring-webflux/pom.xml
index 594d95750..f1737a477 100644
--- a/mcp-spring/mcp-spring-webflux/pom.xml
+++ b/mcp-spring/mcp-spring-webflux/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.17.0-SNAPSHOT
+		0.18.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webflux
@@ -25,19 +25,19 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.17.0-SNAPSHOT
+            0.18.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-spring/mcp-spring-webmvc/pom.xml b/mcp-spring/mcp-spring-webmvc/pom.xml
index 6460f652f..df18b1b8b 100644
--- a/mcp-spring/mcp-spring-webmvc/pom.xml
+++ b/mcp-spring/mcp-spring-webmvc/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.17.0-SNAPSHOT
+		0.18.0-SNAPSHOT
 		../../pom.xml
 	
 	mcp-spring-webmvc
@@ -25,13 +25,13 @@
         
             io.modelcontextprotocol.sdk
             mcp-json-jackson2
-            0.17.0-SNAPSHOT
+            0.18.0-SNAPSHOT
         
 
         
 			io.modelcontextprotocol.sdk
 			mcp
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 		
 
 		
@@ -43,14 +43,14 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-test
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 			test
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-spring-webflux
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 			test
 		
 
diff --git a/mcp-test/pom.xml b/mcp-test/pom.xml
index 3fbd028f4..7fc22e5d2 100644
--- a/mcp-test/pom.xml
+++ b/mcp-test/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.17.0-SNAPSHOT
+		0.18.0-SNAPSHOT
 	
 	mcp-test
 	jar
@@ -24,7 +24,7 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 		
 
 		
diff --git a/mcp/pom.xml b/mcp/pom.xml
index 270dc2a1f..0e0ed1288 100644
--- a/mcp/pom.xml
+++ b/mcp/pom.xml
@@ -6,7 +6,7 @@
 	
 		io.modelcontextprotocol.sdk
 		mcp-parent
-		0.17.0-SNAPSHOT
+		0.18.0-SNAPSHOT
 	
 	mcp
 	jar
@@ -25,13 +25,13 @@
 		
 			io.modelcontextprotocol.sdk
 			mcp-json-jackson2
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 		
 
 		
 			io.modelcontextprotocol.sdk
 			mcp-core
-			0.17.0-SNAPSHOT
+			0.18.0-SNAPSHOT
 		
 	
 
diff --git a/pom.xml b/pom.xml
index ca9ce7be4..52f83dba2 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
 
 	io.modelcontextprotocol.sdk
 	mcp-parent
-	0.17.0-SNAPSHOT
+	0.18.0-SNAPSHOT
 
 	pom
 	https://github.com/modelcontextprotocol/java-sdk

From d3d88425e8f8b2be9a699edc0b925114d1b08488 Mon Sep 17 00:00:00 2001
From: ashakirin <2254222+ashakirin@users.noreply.github.com>
Date: Mon, 15 Dec 2025 15:44:31 +0100
Subject: [PATCH 118/125] fix: Fixed html encoding in javadoc (#727)

---
 .../src/main/java/io/modelcontextprotocol/json/TypeRef.java     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java b/mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java
index 725513c66..ab37b43f3 100644
--- a/mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java
+++ b/mcp-json/src/main/java/io/modelcontextprotocol/json/TypeRef.java
@@ -9,7 +9,7 @@
 
 /**
  * Captures generic type information at runtime for parameterized JSON (de)serialization.
- * Usage: TypeRef> ref = new TypeRef<>(){};
+ * Usage: TypeRef<List<Foo>> ref = new TypeRef<>(){};
  */
 public abstract class TypeRef {
 

From fa9dac88c5aad7342c1cdce8be784d9c6ff0af84 Mon Sep 17 00:00:00 2001
From: Jonathan Hefner 
Date: Mon, 15 Dec 2025 08:52:13 -0600
Subject: [PATCH 119/125] fix: Enable javadoc generation for modules with OSGi
 metadata (#705)

fix: enable javadoc HTML generation by using legacyMode
---
 pom.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pom.xml b/pom.xml
index 52f83dba2..67adb4d9a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -75,7 +75,7 @@
 		3.11.0
 		3.1.2
 		3.5.2
-		3.5.0
+		3.11.2
 		3.3.0
 		0.8.10
 		1.5.0
@@ -279,6 +279,7 @@
 						${maven-javadoc-plugin.version}
 						
 							false
+							true
 							false
 							none
 							

From e7901da0100635be7f4631f3d5e9a6dd13bdcfb4 Mon Sep 17 00:00:00 2001
From: Rohit 
Date: Thu, 8 Jan 2026 10:29:39 -0800
Subject: [PATCH 120/125] fix: Support form and url fields in Elicitation
 capability per 2025-11-25 spec (#731)

Update the ClientCapabilities.Elicitation record to accept optional "form"
and "url" fields as defined in the MCP 2025-11-25 specification.

Previously, deserializing an InitializeRequest with
`{"capabilities":{"elicitation":{"form":{}}}}` would fail with
UnrecognizedPropertyException because the Elicitation record was empty.

Changes:
- Add nested Form and Url marker records to Elicitation
- Add no-arg constructor for backward compatibility (serializes to {})
- Add elicitation(boolean form, boolean url) builder method
- Add comprehensive tests for deserialization and serialization

Fixes #724
---
 .../modelcontextprotocol/spec/McpSchema.java  |  57 +++++++++-
 .../spec/McpSchemaTests.java                  | 101 ++++++++++++++++++
 2 files changed, 157 insertions(+), 1 deletion(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 734cff237..b58f1c552 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -416,9 +416,47 @@ public record Sampling() {
 		 * maintain control over user interactions and data sharing while enabling servers
 		 * to gather necessary information dynamically. Servers can request structured
 		 * data from users with optional JSON schemas to validate responses.
+		 *
+		 * 
    
+		 * Per the 2025-11-25 spec, clients can declare support for specific elicitation
+		 * modes:
+		 * 
      
+		 * 
    • {@code form} - In-band structured data collection with optional schema
+		 * validation
      • 
+		 * 
    • {@code url} - Out-of-band interaction via URL navigation
      • 
+		 * 
    
+		 *
+		 * 
    
+		 * For backward compatibility, an empty elicitation object {@code {}} is
+		 * equivalent to declaring support for form mode only.
+		 *
+		 * @param form support for in-band form-based elicitation
+		 * @param url support for out-of-band URL-based elicitation
 		 */
 		@JsonInclude(JsonInclude.Include.NON_ABSENT)
-		public record Elicitation() {
+		public record Elicitation(@JsonProperty("form") Form form, @JsonProperty("url") Url url) {
+
+			/**
+			 * Marker record indicating support for form-based elicitation mode.
+			 */
+			@JsonInclude(JsonInclude.Include.NON_ABSENT)
+			public record Form() {
+			}
+
+			/**
+			 * Marker record indicating support for URL-based elicitation mode.
+			 */
+			@JsonInclude(JsonInclude.Include.NON_ABSENT)
+			public record Url() {
+			}
+
+			/**
+			 * Creates an Elicitation with default settings (backward compatible, produces
+			 * empty JSON object).
+			 */
+			public Elicitation() {
+				this(null, null);
+			}
 		}
 
 		public static Builder builder() {
@@ -450,11 +488,28 @@ public Builder sampling() {
 				return this;
 			}
 
+			/**
+			 * Enables elicitation capability with default settings (backward compatible,
+			 * produces empty JSON object).
+			 * @return this builder
+			 */
 			public Builder elicitation() {
 				this.elicitation = new Elicitation();
 				return this;
 			}
 
+			/**
+			 * Enables elicitation capability with explicit form and/or url mode support.
+			 * @param form whether to support form-based elicitation
+			 * @param url whether to support URL-based elicitation
+			 * @return this builder
+			 */
+			public Builder elicitation(boolean form, boolean url) {
+				this.elicitation = new Elicitation(form ? new Elicitation.Form() : null,
+						url ? new Elicitation.Url() : null);
+				return this;
+			}
+
 			public ClientCapabilities build() {
 				return new ClientCapabilities(experimental, roots, sampling, elicitation);
 			}
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
index 0926eebae..6b0004cb9 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java
@@ -1618,6 +1618,107 @@ void testListRootsResult() throws Exception {
 
 	}
 
+	// Elicitation Capability Tests (Issue #724)
+
+	@Test
+	void testElicitationCapabilityWithFormField() throws Exception {
+		// Test that elicitation with "form" field can be deserialized (2025-11-25 spec)
+		String json = """
+				{"protocolVersion":"2024-11-05","capabilities":{"elicitation":{"form":{}}},"clientInfo":{"name":"test-client","version":"1.0.0"}}
+				""";
+
+		McpSchema.InitializeRequest request = JSON_MAPPER.readValue(json, McpSchema.InitializeRequest.class);
+
+		assertThat(request).isNotNull();
+		assertThat(request.capabilities()).isNotNull();
+		assertThat(request.capabilities().elicitation()).isNotNull();
+	}
+
+	@Test
+	void testElicitationCapabilityWithFormAndUrlFields() throws Exception {
+		// Test that elicitation with both "form" and "url" fields can be deserialized
+		String json = """
+				{"protocolVersion":"2024-11-05","capabilities":{"elicitation":{"form":{},"url":{}}},"clientInfo":{"name":"test-client","version":"1.0.0"}}
+				""";
+
+		McpSchema.InitializeRequest request = JSON_MAPPER.readValue(json, McpSchema.InitializeRequest.class);
+
+		assertThat(request).isNotNull();
+		assertThat(request.capabilities()).isNotNull();
+		assertThat(request.capabilities().elicitation()).isNotNull();
+	}
+
+	@Test
+	void testElicitationCapabilityBackwardCompatibilityEmptyObject() throws Exception {
+		// Test backward compatibility: empty elicitation {} should still work
+		String json = """
+				{"protocolVersion":"2024-11-05","capabilities":{"elicitation":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}
+				""";
+
+		McpSchema.InitializeRequest request = JSON_MAPPER.readValue(json, McpSchema.InitializeRequest.class);
+
+		assertThat(request).isNotNull();
+		assertThat(request.capabilities()).isNotNull();
+		assertThat(request.capabilities().elicitation()).isNotNull();
+	}
+
+	@Test
+	void testElicitationCapabilityBuilderBackwardCompatibility() throws Exception {
+		// Test that the existing builder API still works and produces valid JSON
+		McpSchema.ClientCapabilities capabilities = McpSchema.ClientCapabilities.builder().elicitation().build();
+
+		assertThat(capabilities.elicitation()).isNotNull();
+
+		// Serialize and verify it produces valid JSON (should be {} for backward compat)
+		String json = JSON_MAPPER.writeValueAsString(capabilities);
+		assertThat(json).contains("\"elicitation\"");
+	}
+
+	@Test
+	void testElicitationCapabilitySerializationRoundTrip() throws Exception {
+		// Test that serialization and deserialization round-trip works
+		McpSchema.ClientCapabilities original = McpSchema.ClientCapabilities.builder().elicitation().build();
+
+		String json = JSON_MAPPER.writeValueAsString(original);
+		McpSchema.ClientCapabilities deserialized = JSON_MAPPER.readValue(json, McpSchema.ClientCapabilities.class);
+
+		assertThat(deserialized.elicitation()).isNotNull();
+	}
+
+	@Test
+	void testElicitationCapabilityBuilderWithFormAndUrl() throws Exception {
+		// Test the new builder method that explicitly sets form and url support
+		McpSchema.ClientCapabilities capabilities = McpSchema.ClientCapabilities.builder()
+			.elicitation(true, true)
+			.build();
+
+		assertThat(capabilities.elicitation()).isNotNull();
+		assertThat(capabilities.elicitation().form()).isNotNull();
+		assertThat(capabilities.elicitation().url()).isNotNull();
+
+		// Verify serialization produces the expected JSON
+		String json = JSON_MAPPER.writeValueAsString(capabilities);
+		assertThatJson(json).when(Option.IGNORING_ARRAY_ORDER).isObject().containsKey("elicitation");
+		assertThat(json).contains("\"form\"");
+		assertThat(json).contains("\"url\"");
+	}
+
+	@Test
+	void testElicitationCapabilityBuilderFormOnly() throws Exception {
+		// Test builder with form only
+		McpSchema.ClientCapabilities capabilities = McpSchema.ClientCapabilities.builder()
+			.elicitation(true, false)
+			.build();
+
+		assertThat(capabilities.elicitation()).isNotNull();
+		assertThat(capabilities.elicitation().form()).isNotNull();
+		assertThat(capabilities.elicitation().url()).isNull();
+
+		String json = JSON_MAPPER.writeValueAsString(capabilities);
+		assertThat(json).contains("\"form\"");
+		assertThat(json).doesNotContain("\"url\"");
+	}
+
 	// Progress Notification Tests
 
 	@Test

From dce48929a5ad589642843b84adfcfa135fff62c3 Mon Sep 17 00:00:00 2001
From: Sergio del Amo 
Date: Thu, 8 Jan 2026 20:25:43 +0100
Subject: [PATCH 121/125] add 2025-11-25 version to ProtocolVersions (#733)

---
 .../java/io/modelcontextprotocol/spec/ProtocolVersions.java  | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
index d8cb913a5..4ec1424c1 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
@@ -20,4 +20,9 @@ public interface ProtocolVersions {
 	 */
 	String MCP_2025_06_18 = "2025-06-18";
 
+    /**
+     * MCP protocol version for 2025-11-25.
+     * https://modelcontextprotocol.io/specification/2025-11-25
+     */
+    String MCP_2025_11_25 = "2025-11-25";
 }

From cb533b2e0e8f93f3e3e76c2ca1db84b6548ab84c Mon Sep 17 00:00:00 2001
From: Christian Tzolov 
Date: Thu, 8 Jan 2026 20:26:39 +0100
Subject: [PATCH 122/125] Fix fomratting

Signed-off-by: Christian Tzolov 
---
 .../modelcontextprotocol/spec/ProtocolVersions.java   | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
index 4ec1424c1..d3d34db62 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/ProtocolVersions.java
@@ -20,9 +20,10 @@ public interface ProtocolVersions {
 	 */
 	String MCP_2025_06_18 = "2025-06-18";
 
-    /**
-     * MCP protocol version for 2025-11-25.
-     * https://modelcontextprotocol.io/specification/2025-11-25
-     */
-    String MCP_2025_11_25 = "2025-11-25";
+	/**
+	 * MCP protocol version for 2025-11-25.
+	 * https://modelcontextprotocol.io/specification/2025-11-25
+	 */
+	String MCP_2025_11_25 = "2025-11-25";
+
 }

From b518393cfd5a1108101b2a2bfce0c4798b7a923f Mon Sep 17 00:00:00 2001
From: Jordan Zimmerman 
Date: Thu, 8 Jan 2026 19:29:05 +0000
Subject: [PATCH 123/125] Expose resourcesUpdateConsumer() in sync client
 (#735)

`resourcesUpdateConsumer()` was missing from the sync client. Add it.
---
 .../client/McpClient.java                     | 37 ++++++++++++++-----
 .../client/AbstractMcpSyncClientTests.java    |  4 +-
 .../client/AbstractMcpSyncClientTests.java    |  4 +-
 3 files changed, 33 insertions(+), 12 deletions(-)

diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
index 421f2fc7f..c9989f832 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java
@@ -4,17 +4,8 @@
 
 package io.modelcontextprotocol.client;
 
-import java.time.Duration;
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.function.Consumer;
-import java.util.function.Function;
-import java.util.function.Supplier;
-
-import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
@@ -28,6 +19,15 @@
 import io.modelcontextprotocol.util.Assert;
 import reactor.core.publisher.Mono;
 
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
 /**
  * Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that
  * enables AI models to interact with external tools and resources through a standardized
@@ -75,6 +75,7 @@
  *     .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> System.out.println("Resources updated: " + resources)))
  *     .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> System.out.println("Prompts updated: " + prompts)))
  *     .loggingConsumer(message -> Mono.fromRunnable(() -> System.out.println("Log message: " + message)))
+ *     .resourcesUpdateConsumer(resourceContents -> Mono.fromRunnable(() -> System.out.println("Resources contents updated: " + resourceContents)))
  *     .build();
  * }
    
  *
@@ -346,6 +347,22 @@ public SyncSpec resourcesChangeConsumer(Consumer> resou
 			return this;
 		}
 
+		/**
+		 * Adds a consumer to be notified when a specific resource is updated. This allows
+		 * the client to react to changes in individual resources, such as updates to
+		 * their content or metadata.
+		 * @param resourcesUpdateConsumer A consumer function that processes the updated
+		 * resource and returns a Mono indicating the completion of the processing. Must
+		 * not be null.
+		 * @return This builder instance for method chaining.
+		 * @throws IllegalArgumentException If the resourcesUpdateConsumer is null.
+		 */
+		public SyncSpec resourcesUpdateConsumer(Consumer> resourcesUpdateConsumer) {
+			Assert.notNull(resourcesUpdateConsumer, "Resources update consumer must not be null");
+			this.resourcesUpdateConsumers.add(resourcesUpdateConsumer);
+			return this;
+		}
+
 		/**
 		 * Adds a consumer to be notified when the available prompts change. This allows
 		 * the client to react to changes in the server's prompt templates, such as new
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 6ccf56d73..7ce12772c 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -536,11 +536,13 @@ void testNotificationHandlers() {
 		AtomicBoolean toolsNotificationReceived = new AtomicBoolean(false);
 		AtomicBoolean resourcesNotificationReceived = new AtomicBoolean(false);
 		AtomicBoolean promptsNotificationReceived = new AtomicBoolean(false);
+		AtomicBoolean resourcesUpdatedNotificationReceived = new AtomicBoolean(false);
 
 		withClient(createMcpTransport(),
 				builder -> builder.toolsChangeConsumer(tools -> toolsNotificationReceived.set(true))
 					.resourcesChangeConsumer(resources -> resourcesNotificationReceived.set(true))
-					.promptsChangeConsumer(prompts -> promptsNotificationReceived.set(true)),
+					.promptsChangeConsumer(prompts -> promptsNotificationReceived.set(true))
+					.resourcesUpdateConsumer(resources -> resourcesUpdatedNotificationReceived.set(true)),
 				client -> {
 
 					assertThatCode(() -> {
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index e1ffd2c75..21e0c1492 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -535,11 +535,13 @@ void testNotificationHandlers() {
 		AtomicBoolean toolsNotificationReceived = new AtomicBoolean(false);
 		AtomicBoolean resourcesNotificationReceived = new AtomicBoolean(false);
 		AtomicBoolean promptsNotificationReceived = new AtomicBoolean(false);
+		AtomicBoolean resourcesUpdatedNotificationReceived = new AtomicBoolean(false);
 
 		withClient(createMcpTransport(),
 				builder -> builder.toolsChangeConsumer(tools -> toolsNotificationReceived.set(true))
 					.resourcesChangeConsumer(resources -> resourcesNotificationReceived.set(true))
-					.promptsChangeConsumer(prompts -> promptsNotificationReceived.set(true)),
+					.promptsChangeConsumer(prompts -> promptsNotificationReceived.set(true))
+					.resourcesUpdateConsumer(resources -> resourcesUpdatedNotificationReceived.set(true)),
 				client -> {
 
 					assertThatCode(() -> {

From f7a460fb505aeba239165f9bc4ef508a77ba102a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Deleuze?=
 
Date: Mon, 12 Jan 2026 15:55:20 +0100
Subject: [PATCH 124/125] Upgrade to testcontainers 1.21.4 (#743)

To fix a "docker-machine executable was not found on PATH"
error with recent Docker versions (impact at least Docker
4.55 and 4.56).
---
 pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pom.xml b/pom.xml
index 67adb4d9a..f8bc3a9c2 100644
--- a/pom.xml
+++ b/pom.xml
@@ -62,7 +62,7 @@
 		3.27.6
 		5.10.2
 		5.20.0
-		1.20.4
+		1.21.4
 		1.17.8
 		1.21.0
 

From af65356416ba43037e59980edaa44438d9d66a70 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dariusz=20J=C4=99drzejczyk?=
 
Date: Tue, 20 Jan 2026 16:09:41 +0100
Subject: [PATCH 125/125] Fix everything-server-based integration tests (#756)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Pin `npx @modelcontextprotocol/server-everything` version to `2025.12.18`.
* Replace `tzolov/mcp-everything-server` Docker image with `node:lts-alpine` + `npx` command.
* Handle HTTP 202 special case.
* Fix test assertions.

The recent rollout of everything-server broke integration tests which take the latest version from the node registry.
This PR unifies the everything-server usage - the Testcontainers Docker setup uses the same version as the STDIO npx-based tests and no longer relies on tzolov/mcp-everything-server.

Signed-off-by: Dariusz Jędrzejczyk 
---
 .../HttpClientStreamableHttpTransport.java    |  4 +-
 ...AbstractMcpAsyncClientResiliencyTests.java |  5 +-
 .../client/AbstractMcpAsyncClientTests.java   | 94 +++++++++---------
 .../client/AbstractMcpSyncClientTests.java    |  2 +-
 ...pClientStreamableHttpAsyncClientTests.java |  5 +-
 ...tpClientStreamableHttpSyncClientTests.java |  5 +-
 ...pSseMcpAsyncClientLostConnectionTests.java |  5 +-
 .../client/HttpSseMcpAsyncClientTests.java    |  5 +-
 .../client/HttpSseMcpSyncClientTests.java     |  5 +-
 .../client/ServerParameterUtils.java          |  6 +-
 .../HttpClientSseClientTransportTests.java    |  4 +-
 ...HttpClientStreamableHttpTransportTest.java |  4 +-
 .../WebClientStreamableHttpTransport.java     |  3 +-
 ...bClientStreamableHttpAsyncClientTests.java |  5 +-
 ...ebClientStreamableHttpSyncClientTests.java |  5 +-
 .../client/WebFluxSseMcpAsyncClientTests.java |  7 +-
 .../client/WebFluxSseMcpSyncClientTests.java  |  5 +-
 .../WebClientStreamableHttpTransportTest.java |  4 +-
 .../WebFluxSseClientTransportTests.java       |  4 +-
 ...AbstractMcpAsyncClientResiliencyTests.java |  5 +-
 .../client/AbstractMcpAsyncClientTests.java   | 99 ++++++++++---------
 .../client/AbstractMcpSyncClientTests.java    |  2 +-
 22 files changed, 144 insertions(+), 139 deletions(-)

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 e41f45ebb..0a8dff363 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
@@ -491,7 +491,9 @@ public Mono sendMessage(McpSchema.JSONRPCMessage sentMessage) {
 						.firstValue(HttpHeaders.CONTENT_LENGTH)
 						.orElse(null);
 
-					if (contentType.isBlank() || "0".equals(contentLength)) {
+					// For empty content or HTTP code 202 (ACCEPTED), assume success
+					if (contentType.isBlank() || "0".equals(contentLength) || statusCode == 202) {
+						// if (contentType.isBlank() || "0".equals(contentLength)) {
 						logger.debug("No body returned for POST in session {}", sessionRepresentation);
 						// No content type means no response body, so we can just
 						// return an empty stream
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index 183b8a365..18a5cb999 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -48,10 +48,9 @@ public abstract class AbstractMcpAsyncClientResiliencyTests {
 	static Network network = Network.newNetwork();
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withNetwork(network)
 		.withNetworkAliases("everything-server")
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index 57a223ea2..5b7877971 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -72,7 +72,7 @@ protected Duration getRequestTimeout() {
 	}
 
 	protected Duration getInitializationTimeout() {
-		return Duration.ofSeconds(2);
+		return Duration.ofSeconds(20);
 	}
 
 	McpAsyncClient client(McpClientTransport transport) {
@@ -503,57 +503,64 @@ void testRemoveNonExistentRoot() {
 
 	@Test
 	void testReadResource() {
+		AtomicInteger resourceCount = new AtomicInteger();
 		withClient(createMcpTransport(), client -> {
 			Flux resources = client.initialize()
 				.then(client.listResources(null))
-				.flatMapMany(r -> Flux.fromIterable(r.resources()))
+				.flatMapMany(r -> {
+					List l = r.resources();
+					resourceCount.set(l.size());
+					return Flux.fromIterable(l);
+				})
 				.flatMap(r -> client.readResource(r));
 
-			StepVerifier.create(resources).recordWith(ArrayList::new).consumeRecordedWith(readResourceResults -> {
-
-				for (ReadResourceResult result : readResourceResults) {
-
-					assertThat(result).isNotNull();
-					assertThat(result.contents()).isNotNull().isNotEmpty();
-
-					// Validate each content item
-					for (ResourceContents content : result.contents()) {
-						assertThat(content).isNotNull();
-						assertThat(content.uri()).isNotNull().isNotEmpty();
-						assertThat(content.mimeType()).isNotNull().isNotEmpty();
-
-						// Validate content based on its type with more comprehensive
-						// checks
-						switch (content.mimeType()) {
-							case "text/plain" -> {
-								TextResourceContents textContent = assertInstanceOf(TextResourceContents.class,
-										content);
-								assertThat(textContent.text()).isNotNull().isNotEmpty();
-								assertThat(textContent.uri()).isNotEmpty();
-							}
-							case "application/octet-stream" -> {
-								BlobResourceContents blobContent = assertInstanceOf(BlobResourceContents.class,
-										content);
-								assertThat(blobContent.blob()).isNotNull().isNotEmpty();
-								assertThat(blobContent.uri()).isNotNull().isNotEmpty();
-								// Validate base64 encoding format
-								assertThat(blobContent.blob()).matches("^[A-Za-z0-9+/]*={0,2}$");
-							}
-							default -> {
-
-								// Still validate basic properties
-								if (content instanceof TextResourceContents textContent) {
-									assertThat(textContent.text()).isNotNull();
+			StepVerifier.create(resources)
+				.recordWith(ArrayList::new)
+				.thenConsumeWhile(res -> true)
+				.consumeRecordedWith(readResourceResults -> {
+					assertThat(readResourceResults.size()).isEqualTo(resourceCount.get());
+					for (ReadResourceResult result : readResourceResults) {
+
+						assertThat(result).isNotNull();
+						assertThat(result.contents()).isNotNull().isNotEmpty();
+
+						// Validate each content item
+						for (ResourceContents content : result.contents()) {
+							assertThat(content).isNotNull();
+							assertThat(content.uri()).isNotNull().isNotEmpty();
+							assertThat(content.mimeType()).isNotNull().isNotEmpty();
+
+							// Validate content based on its type with more comprehensive
+							// checks
+							switch (content.mimeType()) {
+								case "text/plain" -> {
+									TextResourceContents textContent = assertInstanceOf(TextResourceContents.class,
+											content);
+									assertThat(textContent.text()).isNotNull().isNotEmpty();
+									assertThat(textContent.uri()).isNotEmpty();
+								}
+								case "application/octet-stream" -> {
+									BlobResourceContents blobContent = assertInstanceOf(BlobResourceContents.class,
+											content);
+									assertThat(blobContent.blob()).isNotNull().isNotEmpty();
+									assertThat(blobContent.uri()).isNotNull().isNotEmpty();
+									// Validate base64 encoding format
+									assertThat(blobContent.blob()).matches("^[A-Za-z0-9+/]*={0,2}$");
 								}
-								else if (content instanceof BlobResourceContents blobContent) {
-									assertThat(blobContent.blob()).isNotNull();
+								default -> {
+
+									// Still validate basic properties
+									if (content instanceof TextResourceContents textContent) {
+										assertThat(textContent.text()).isNotNull();
+									}
+									else if (content instanceof BlobResourceContents blobContent) {
+										assertThat(blobContent.blob()).isNotNull();
+									}
 								}
 							}
 						}
 					}
-				}
-			})
-				.expectNextCount(10) // Expect 10 elements
+				})
 				.verifyComplete();
 		});
 	}
@@ -693,7 +700,6 @@ void testInitializeWithAllCapabilities() {
 					assertThat(result.capabilities()).isNotNull();
 				}).verifyComplete());
 	}
-
 	// ---------------------------------------
 	// Logging Tests
 	// ---------------------------------------
@@ -773,7 +779,7 @@ void testSampling() {
 							if (!(content instanceof McpSchema.TextContent text))
 								return;
 
-							assertThat(text.text()).endsWith(response); // Prefixed
+							assertThat(text.text()).contains(response);
 						});
 
 						// Verify sampling request parameters received in our callback
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 7ce12772c..c67fa86bb 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -625,7 +625,7 @@ void testSampling() {
 					if (!(content instanceof McpSchema.TextContent text))
 						return;
 
-					assertThat(text.text()).endsWith(response); // Prefixed
+					assertThat(text.text()).contains(response);
 				});
 
 				// Verify sampling request parameters received in our callback
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
index c4157bc37..a29ca16db 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpAsyncClientTests.java
@@ -17,10 +17,9 @@ public class HttpClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncCl
 
 	private static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
index d59ae35b4..ee5e5de05 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpClientStreamableHttpSyncClientTests.java
@@ -30,10 +30,9 @@ public class HttpClientStreamableHttpSyncClientTests extends AbstractMcpSyncClie
 
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
index 30e7fe913..e2037f415 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientLostConnectionTests.java
@@ -36,10 +36,9 @@ public class HttpSseMcpAsyncClientLostConnectionTests {
 	static Network network = Network.newNetwork();
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js sse")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withNetwork(network)
 		.withNetworkAliases("everything-server")
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
index f467289ff..91a8b6c82 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpAsyncClientTests.java
@@ -23,10 +23,9 @@ class HttpSseMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
 	private static String host = "http://localhost:3004";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js sse")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
index 483d38669..d903b3b3c 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/HttpSseMcpSyncClientTests.java
@@ -36,10 +36,9 @@ class HttpSseMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
 	static String host = "http://localhost:3003";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js sse")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
index 63ec015fe..547ccc52f 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/ServerParameterUtils.java
@@ -10,10 +10,12 @@ private ServerParameterUtils() {
 	public static ServerParameters createServerParameters() {
 		if (System.getProperty("os.name").toLowerCase().contains("win")) {
 			return ServerParameters.builder("cmd.exe")
-				.args("/c", "npx.cmd", "-y", "@modelcontextprotocol/server-everything", "stdio")
+				.args("/c", "npx.cmd", "-y", "@modelcontextprotocol/server-everything@2025.12.18", "stdio")
 				.build();
 		}
-		return ServerParameters.builder("npx").args("-y", "@modelcontextprotocol/server-everything", "stdio").build();
+		return ServerParameters.builder("npx")
+			.args("-y", "@modelcontextprotocol/server-everything@2025.12.18", "stdio")
+			.build();
 	}
 
 }
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
index c5c365798..a24805a30 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransportTests.java
@@ -58,8 +58,8 @@ class HttpClientSseClientTransportTests {
 	static String host = "http://localhost:3001";
 
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js sse")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
index f9536b690..2ade30e17 100644
--- a/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
+++ b/mcp-core/src/test/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransportTest.java
@@ -40,8 +40,8 @@ class HttpClientStreamableHttpTransportTest {
 		.create(Map.of("test-transport-context-key", "some-value"));
 
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
index a8a4762c2..0b5ce55cd 100644
--- a/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
+++ b/mcp-spring/mcp-spring-webflux/src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java
@@ -318,7 +318,8 @@ public Mono sendMessage(McpSchema.JSONRPCMessage message) {
 						long contentLength = response.headers().contentLength().orElse(-1);
 						// Existing SDKs consume notifications with no response body nor
 						// content type
-						if (contentType.isEmpty() || contentLength == 0) {
+						if (contentType.isEmpty() || contentLength == 0
+								|| response.statusCode().equals(HttpStatus.ACCEPTED)) {
 							logger.trace("Message was successfully sent via POST for session {}",
 									sessionRepresentation);
 							// signal the caller that the message was successfully
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
index 1a4eedd15..cf4458506 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpAsyncClientTests.java
@@ -19,10 +19,9 @@ public class WebClientStreamableHttpAsyncClientTests extends AbstractMcpAsyncCli
 
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
index 16f1d79a6..f47ba5277 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebClientStreamableHttpSyncClientTests.java
@@ -19,10 +19,9 @@ public class WebClientStreamableHttpSyncClientTests extends AbstractMcpSyncClien
 
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
index 0a92beac4..72c0168d5 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpAsyncClientTests.java
@@ -26,13 +26,12 @@ class WebFluxSseMcpAsyncClientTests extends AbstractMcpAsyncClientTests {
 
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js sse")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
-		.waitingFor(Wait.forHttp("/").forStatusCode(404));
+		.waitingFor(Wait.forHttp("/").forStatusCode(404).forPort(3001));
 
 	@Override
 	protected McpClientTransport createMcpTransport() {
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
index 0f35f9f0d..b483029e0 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/WebFluxSseMcpSyncClientTests.java
@@ -25,10 +25,9 @@ class WebFluxSseMcpSyncClientTests extends AbstractMcpSyncClientTests {
 
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js sse")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
index e2fcf91f7..34e422be4 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransportTest.java
@@ -20,8 +20,8 @@ class WebClientStreamableHttpTransportTest {
 	static WebClient.Builder builder;
 
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
index 1150e47f5..a29c9d69c 100644
--- a/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
+++ b/mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/client/transport/WebFluxSseClientTransportTests.java
@@ -47,8 +47,8 @@ class WebFluxSseClientTransportTests {
 	static String host = "http://localhost:3001";
 
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js sse")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 sse")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withExposedPorts(3001)
 		.waitingFor(Wait.forHttp("/").forStatusCode(404));
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
index d0b1c46a2..338eaf931 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientResiliencyTests.java
@@ -47,10 +47,9 @@ public abstract class AbstractMcpAsyncClientResiliencyTests {
 	static Network network = Network.newNetwork();
 	static String host = "http://localhost:3001";
 
-	// Uses the https://github.com/tzolov/mcp-everything-server-docker-image
 	@SuppressWarnings("resource")
-	static GenericContainer container = new GenericContainer<>("docker.io/tzolov/mcp-everything-server:v3")
-		.withCommand("node dist/index.js streamableHttp")
+	static GenericContainer container = new GenericContainer<>("docker.io/node:lts-alpine3.23")
+		.withCommand("npx -y @modelcontextprotocol/server-everything@2025.12.18 streamableHttp")
 		.withLogConsumer(outputFrame -> System.out.println(outputFrame.getUtf8String()))
 		.withNetwork(network)
 		.withNetworkAliases("everything-server")
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
index e1b051204..bee8f4f16 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.client;
 
+import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -52,8 +53,6 @@
 import reactor.core.publisher.Sinks;
 import reactor.test.StepVerifier;
 
-import static io.modelcontextprotocol.util.McpJsonMapperUtils.JSON_MAPPER;
-
 /**
  * Test suite for the {@link McpAsyncClient} that can be used with different
  * {@link McpTransport} implementations.
@@ -72,7 +71,7 @@ protected Duration getRequestTimeout() {
 	}
 
 	protected Duration getInitializationTimeout() {
-		return Duration.ofSeconds(2);
+		return Duration.ofSeconds(20);
 	}
 
 	McpAsyncClient client(McpClientTransport transport) {
@@ -503,57 +502,64 @@ void testRemoveNonExistentRoot() {
 
 	@Test
 	void testReadResource() {
+		AtomicInteger resourceCount = new AtomicInteger();
 		withClient(createMcpTransport(), client -> {
 			Flux resources = client.initialize()
 				.then(client.listResources(null))
-				.flatMapMany(r -> Flux.fromIterable(r.resources()))
+				.flatMapMany(r -> {
+					List l = r.resources();
+					resourceCount.set(l.size());
+					return Flux.fromIterable(l);
+				})
 				.flatMap(r -> client.readResource(r));
 
-			StepVerifier.create(resources).recordWith(ArrayList::new).consumeRecordedWith(readResourceResults -> {
-
-				for (ReadResourceResult result : readResourceResults) {
-
-					assertThat(result).isNotNull();
-					assertThat(result.contents()).isNotNull().isNotEmpty();
-
-					// Validate each content item
-					for (ResourceContents content : result.contents()) {
-						assertThat(content).isNotNull();
-						assertThat(content.uri()).isNotNull().isNotEmpty();
-						assertThat(content.mimeType()).isNotNull().isNotEmpty();
-
-						// Validate content based on its type with more comprehensive
-						// checks
-						switch (content.mimeType()) {
-							case "text/plain" -> {
-								TextResourceContents textContent = assertInstanceOf(TextResourceContents.class,
-										content);
-								assertThat(textContent.text()).isNotNull().isNotEmpty();
-								assertThat(textContent.uri()).isNotEmpty();
-							}
-							case "application/octet-stream" -> {
-								BlobResourceContents blobContent = assertInstanceOf(BlobResourceContents.class,
-										content);
-								assertThat(blobContent.blob()).isNotNull().isNotEmpty();
-								assertThat(blobContent.uri()).isNotNull().isNotEmpty();
-								// Validate base64 encoding format
-								assertThat(blobContent.blob()).matches("^[A-Za-z0-9+/]*={0,2}$");
-							}
-							default -> {
-
-								// Still validate basic properties
-								if (content instanceof TextResourceContents textContent) {
-									assertThat(textContent.text()).isNotNull();
+			StepVerifier.create(resources)
+				.recordWith(ArrayList::new)
+				.thenConsumeWhile(res -> true)
+				.consumeRecordedWith(readResourceResults -> {
+					assertThat(readResourceResults.size()).isEqualTo(resourceCount.get());
+					for (ReadResourceResult result : readResourceResults) {
+
+						assertThat(result).isNotNull();
+						assertThat(result.contents()).isNotNull().isNotEmpty();
+
+						// Validate each content item
+						for (ResourceContents content : result.contents()) {
+							assertThat(content).isNotNull();
+							assertThat(content.uri()).isNotNull().isNotEmpty();
+							assertThat(content.mimeType()).isNotNull().isNotEmpty();
+
+							// Validate content based on its type with more comprehensive
+							// checks
+							switch (content.mimeType()) {
+								case "text/plain" -> {
+									TextResourceContents textContent = assertInstanceOf(TextResourceContents.class,
+											content);
+									assertThat(textContent.text()).isNotNull().isNotEmpty();
+									assertThat(textContent.uri()).isNotEmpty();
 								}
-								else if (content instanceof BlobResourceContents blobContent) {
-									assertThat(blobContent.blob()).isNotNull();
+								case "application/octet-stream" -> {
+									BlobResourceContents blobContent = assertInstanceOf(BlobResourceContents.class,
+											content);
+									assertThat(blobContent.blob()).isNotNull().isNotEmpty();
+									assertThat(blobContent.uri()).isNotNull().isNotEmpty();
+									// Validate base64 encoding format
+									assertThat(blobContent.blob()).matches("^[A-Za-z0-9+/]*={0,2}$");
+								}
+								default -> {
+
+									// Still validate basic properties
+									if (content instanceof TextResourceContents textContent) {
+										assertThat(textContent.text()).isNotNull();
+									}
+									else if (content instanceof BlobResourceContents blobContent) {
+										assertThat(blobContent.blob()).isNotNull();
+									}
 								}
 							}
 						}
 					}
-				}
-			})
-				.expectNextCount(10) // Expect 10 elements
+				})
 				.verifyComplete();
 		});
 	}
@@ -673,7 +679,7 @@ void testInitializeWithElicitationCapability() {
 	@Test
 	void testInitializeWithAllCapabilities() {
 		var capabilities = ClientCapabilities.builder()
-			.experimental(Map.of("feature", "test"))
+			.experimental(Map.of("feature", Map.of("featureFlag", true)))
 			.roots(true)
 			.sampling()
 			.build();
@@ -693,7 +699,6 @@ void testInitializeWithAllCapabilities() {
 					assertThat(result.capabilities()).isNotNull();
 				}).verifyComplete());
 	}
-
 	// ---------------------------------------
 	// Logging Tests
 	// ---------------------------------------
@@ -773,7 +778,7 @@ void testSampling() {
 							if (!(content instanceof McpSchema.TextContent text))
 								return;
 
-							assertThat(text.text()).endsWith(response); // Prefixed
+							assertThat(text.text()).contains(response);
 						});
 
 						// Verify sampling request parameters received in our callback
diff --git a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
index 21e0c1492..26d60568a 100644
--- a/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
+++ b/mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
@@ -624,7 +624,7 @@ void testSampling() {
 					if (!(content instanceof McpSchema.TextContent text))
 						return;
 
-					assertThat(text.text()).endsWith(response); // Prefixed
+					assertThat(text.text()).contains(response);
 				});
 
 				// Verify sampling request parameters received in our callback