supported;
+ try {
+ UnsupportedProtocolVersionData data = this.jsonMapper.convertValue(error.data(),
+ UnsupportedProtocolVersionData.class);
+ supported = data == null ? null : data.supported();
+ }
+ catch (RuntimeException ex) {
+ logger.debug("Ignoring malformed data of a -32022 error: {}", error.data(), ex);
+ return null;
+ }
+ if (supported == null) {
+ return null;
+ }
+ return this.protocolVersions.stream().filter(supported::contains).findFirst().orElse(null);
+ }
+
+ /**
+ * A {@code -32022} answer, caught by {@link #send} to renegotiate the version.
+ */
+ private static final class UnsupportedVersion extends RuntimeException {
+
+ private final transient JSONRPCError error;
+
+ UnsupportedVersion(JSONRPCError error) {
+ super(error.message(), null, false, false);
+ this.error = error;
+ }
+
+ }
+
+}
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/modern/client/Listings.java b/mcp-core/src/main/java/io/modelcontextprotocol/modern/client/Listings.java
new file mode 100644
index 000000000..e386b2a9e
--- /dev/null
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/modern/client/Listings.java
@@ -0,0 +1,74 @@
+/*
+ * Copyright 2026-2026 the original author or authors.
+ */
+
+package io.modelcontextprotocol.modern.client;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Function;
+
+import io.modelcontextprotocol.modern.McpSchema.CacheScope;
+import io.modelcontextprotocol.modern.McpSchema.ListToolsResult;
+import io.modelcontextprotocol.modern.McpSchema.ResultType;
+import io.modelcontextprotocol.modern.McpSchema.Tool;
+import reactor.core.publisher.Mono;
+
+/**
+ * Listings of all pages of a list method.
+ */
+final class Listings {
+
+ private Listings() {
+ }
+
+ /**
+ * Every page of a listing, read one after another until a page has no next cursor or
+ * repeats one.
+ * @param method the list method, for errors
+ * @param lister lists the page at a cursor, {@code null} for the first page
+ * @param nextCursor the next cursor of a page, {@code null} on the last one
+ * @throws McpInvalidResultException if the listing doesn't end within
+ * {@code maxPages} pages
+ */
+ static Mono> pages(String method, Function> lister, Function nextCursor,
+ int maxPages) {
+ return Mono.defer(() -> {
+ Set cursors = new HashSet<>();
+ AtomicInteger read = new AtomicInteger(1);
+ return lister.apply(null).expand(page -> {
+ String cursor = nextCursor.apply(page);
+ if (cursor == null || !cursors.add(cursor)) {
+ return Mono.empty();
+ }
+ if (read.incrementAndGet() > maxPages) {
+ return Mono.error(new McpInvalidResultException(method, ResultType.COMPLETE,
+ "The listing of " + method + " didn't end within " + maxPages + " pages"));
+ }
+ return lister.apply(cursor);
+ }).collectList();
+ });
+ }
+
+ /**
+ * The tools of all {@code pages} as one result, kept for as long as every page may be
+ * kept: the shortest {@code ttlMs}, and a private scope if any page is private.
+ */
+ static ListToolsResult allTools(List pages) {
+ List tools = new ArrayList<>();
+ long ttlMs = Long.MAX_VALUE;
+ CacheScope scope = CacheScope.PUBLIC;
+ for (ListToolsResult page : pages) {
+ tools.addAll(page.tools());
+ ttlMs = Math.min(ttlMs, page.ttlMs() == null ? 0 : page.ttlMs());
+ if (page.cacheScope() != CacheScope.PUBLIC) {
+ scope = CacheScope.PRIVATE;
+ }
+ }
+ return new ListToolsResult(List.copyOf(tools), null, ttlMs, scope, ResultType.COMPLETE, null);
+ }
+
+}
diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpAsyncClient.java b/mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpAsyncClient.java
new file mode 100644
index 000000000..30797eb87
--- /dev/null
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/modern/client/McpAsyncClient.java
@@ -0,0 +1,877 @@
+/*
+ * Copyright 2026-2026 the original author or authors.
+ */
+
+package io.modelcontextprotocol.modern.client;
+
+import java.time.Duration;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Function;
+import java.util.function.UnaryOperator;
+
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.modern.McpException;
+import io.modelcontextprotocol.modern.McpSchema;
+import io.modelcontextprotocol.modern.McpSchema.CacheableResult;
+import io.modelcontextprotocol.modern.McpSchema.CallToolOutcome;
+import io.modelcontextprotocol.modern.McpSchema.CallToolRequest;
+import io.modelcontextprotocol.modern.McpSchema.CallToolResult;
+import io.modelcontextprotocol.modern.McpSchema.CompleteReference;
+import io.modelcontextprotocol.modern.McpSchema.CompleteRequest;
+import io.modelcontextprotocol.modern.McpSchema.CompleteRequest.CompleteArgument;
+import io.modelcontextprotocol.modern.McpSchema.CompleteRequest.CompleteContext;
+import io.modelcontextprotocol.modern.McpSchema.CompleteResult;
+import io.modelcontextprotocol.modern.McpSchema.DiscoverResult;
+import io.modelcontextprotocol.modern.McpSchema.ElicitFormRequest;
+import io.modelcontextprotocol.modern.McpSchema.ElicitUrlRequest;
+import io.modelcontextprotocol.modern.McpSchema.GetPromptOutcome;
+import io.modelcontextprotocol.modern.McpSchema.GetPromptRequest;
+import io.modelcontextprotocol.modern.McpSchema.GetPromptResult;
+import io.modelcontextprotocol.modern.McpSchema.InputRequiredResult;
+import io.modelcontextprotocol.modern.McpSchema.ListPromptsResult;
+import io.modelcontextprotocol.modern.McpSchema.ListResourceTemplatesResult;
+import io.modelcontextprotocol.modern.McpSchema.ListResourcesResult;
+import io.modelcontextprotocol.modern.McpSchema.ListToolsResult;
+import io.modelcontextprotocol.modern.McpSchema.PaginatedRequest;
+import io.modelcontextprotocol.modern.McpSchema.ProgressParams;
+import io.modelcontextprotocol.modern.McpSchema.ReadResourceOutcome;
+import io.modelcontextprotocol.modern.McpSchema.ReadResourceRequest;
+import io.modelcontextprotocol.modern.McpSchema.ReadResourceResult;
+import io.modelcontextprotocol.modern.McpSchema.SubscriptionFilter;
+import io.modelcontextprotocol.modern.McpSchema.Tool;
+import io.modelcontextprotocol.util.Assert;
+import org.jspecify.annotations.Nullable;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+/**
+ * A client for MCP {@value McpSchema#LATEST_PROTOCOL_VERSION} servers, built with
+ * {@link McpClient#async}. Immutable and thread-safe.
+ *
+ * Each operation starts from a request spec, such as {@link #tool(String)}, on which the
+ * call is configured. Specs are immutable: every setting returns a new spec, so a
+ * configured spec can be kept and reused. Their terminals return cold publishers; each
+ * subscription is a new call, sent for the {@link McpTransportContext} found under
+ * {@link McpTransportContext#KEY} in the subscriber's context. Every request, retry and
+ * input handler of the call runs in that context.
+ *
+ * When a tool call, resource read or prompt get is answered with input requests, the
+ * client answers them with the handlers in effect for the call and sends the request
+ * again, until the server completes it. The capabilities each request declares are the
+ * ones those handlers cover.
+ *
+ * Results are emitted on transport threads, so code that reacts to them must not block.
+ *
+ * A call fails with {@link McpException} when the server answers with an error,
+ * {@link McpTimeoutException} when a timeout expires, {@link McpResponseLostException}
+ * when an exchange breaks before its response arrives, and
+ * {@link McpInvalidResultException} when a result can't be accepted.
+ *
+ * @author Dariusz Jędrzejczyk
+ */
+public final class McpAsyncClient {
+
+ private final AsyncClientRequester requester;
+
+ private final DiscoverCache discoverCache = new DiscoverCache();
+
+ McpAsyncClient(AsyncClientRequester requester) {
+ this.requester = requester;
+ }
+
+ /**
+ * Lists the server's tools ({@code tools/list}).
+ */
+ public ListSpec tools() {
+ return new ListSpec<>(this.requester, McpSchema.METHOD_TOOLS_LIST, ListToolsResult.class,
+ this.requester::listedTools, null, this.requester.settings());
+ }
+
+ /**
+ * Lists the server's prompts ({@code prompts/list}).
+ */
+ public ListSpec prompts() {
+ return new ListSpec<>(this.requester, McpSchema.METHOD_PROMPTS_LIST, ListPromptsResult.class,
+ UnaryOperator.identity(), null, this.requester.settings());
+ }
+
+ /**
+ * Lists the server's resources ({@code resources/list}).
+ */
+ public ListSpec resources() {
+ return new ListSpec<>(this.requester, McpSchema.METHOD_RESOURCES_LIST, ListResourcesResult.class,
+ UnaryOperator.identity(), null, this.requester.settings());
+ }
+
+ /**
+ * Lists the server's resource templates ({@code resources/templates/list}).
+ */
+ public ListSpec resourceTemplates() {
+ return new ListSpec<>(this.requester, McpSchema.METHOD_RESOURCES_TEMPLATES_LIST,
+ ListResourceTemplatesResult.class, UnaryOperator.identity(), null, this.requester.settings());
+ }
+
+ /**
+ * Calls the tool named {@code name} ({@code tools/call}).
+ *
+ * When the transport mirrors tool arguments into headers, the arguments the tool's
+ * definition annotates with {@code x-mcp-header} are sent as {@code Mcp-Param-{Name}}
+ * headers. The definition comes from the client's earlier listings of the tools, or
+ * from listing all tools when the client hasn't seen the tool yet. A call the server
+ * rejects for its headers is sent once more after listing the tools again. A tool the
+ * server doesn't list, or whose annotations are invalid, isn't called; the call fails
+ * with {@link IllegalArgumentException}.
+ */
+ public ToolSpec tool(String name) {
+ Assert.hasText(name, "name must not be empty");
+ return new ToolSpec(this.requester, name, null, null, null, null, this.requester.settings());
+ }
+
+ /**
+ * Calls a tool whose definition the caller already has ({@code tools/call}), as
+ * {@link #tool(String)} but with {@code tool} as the tool's definition.
+ */
+ public ToolSpec tool(Tool tool) {
+ Assert.notNull(tool, "tool must not be null");
+ Assert.hasText(tool.name(), "tool name must not be empty");
+ return new ToolSpec(this.requester, tool.name(), tool, null, null, null, this.requester.settings());
+ }
+
+ /**
+ * Reads the resource at {@code uri} ({@code resources/read}).
+ */
+ public ResourceSpec resource(String uri) {
+ Assert.hasText(uri, "uri must not be empty");
+ return new ResourceSpec(this.requester, uri, null, null, this.requester.settings());
+ }
+
+ /**
+ * Gets the prompt named {@code name} ({@code prompts/get}).
+ */
+ public PromptSpec prompt(String name) {
+ Assert.hasText(name, "name must not be empty");
+ return new PromptSpec(this.requester, name, null, null, null, this.requester.settings());
+ }
+
+ /**
+ * Asks for completions of the argument {@code argument} of a prompt or resource
+ * template ({@code completion/complete}), whose value so far is {@code value}.
+ */
+ public CompletionSpec completion(CompleteReference ref, String argument, String value) {
+ Assert.notNull(ref, "ref must not be null");
+ return new CompletionSpec(this.requester, ref, new CompleteArgument(argument, value), null,
+ this.requester.settings());
+ }
+
+ /**
+ * Listens for changes on the server ({@code subscriptions/listen}). The changes to
+ * listen for are set on the returned spec.
+ */
+ public ListenSpec listen() {
+ return new ListenSpec(this.requester, SubscriptionFilter.EMPTY, Map.of());
+ }
+
+ /**
+ * Asks the server for its versions, capabilities, instructions and info
+ * ({@code server/discover}). The result is kept for its {@code ttlMs}, during which
+ * it is emitted without asking the server again.
+ */
+ public Mono discover() {
+ return Mono.defer(() -> {
+ DiscoverResult fresh = this.discoverCache.fresh();
+ if (fresh != null) {
+ return Mono.just(fresh);
+ }
+ return this.requester
+ .call(McpSchema.METHOD_SERVER_DISCOVER, null, Map.of(), this.requester.settings(), DiscoverResult.class)
+ .map(this.discoverCache::keep);
+ });
+ }
+
+ /**
+ * All the server's tools: every page of {@code tools().list()}, as one result that
+ * may be kept for the shortest {@code ttlMs} of its pages, and is private if any page
+ * is. A listing longer than {@link McpClient.Builder#maxListPages maxListPages} fails
+ * with {@link McpInvalidResultException}.
+ *
+ * When the transport mirrors tool arguments into headers, tools whose
+ * {@code x-mcp-header} annotations are invalid are left out of every listing, and
+ * logged.
+ */
+ public Mono listTools() {
+ return Listings
+ .pages(McpSchema.METHOD_TOOLS_LIST, cursor -> tools().cursor(cursor).list(), ListToolsResult::nextCursor,
+ this.requester.maxListPages())
+ .map(Listings::allTools);
+ }
+
+ @Nullable private static Map copy(@Nullable Map map) {
+ return map == null ? null : Collections.unmodifiableMap(new LinkedHashMap<>(map));
+ }
+
+ private static H requireHandler(H handler) {
+ Assert.notNull(handler, "handler must not be null");
+ return handler;
+ }
+
+ /**
+ * Lists one page of a kind of primitive. Immutable.
+ *
+ * @param the list result
+ */
+ public static final class ListSpec {
+
+ private final AsyncClientRequester requester;
+
+ private final String method;
+
+ private final Class resultType;
+
+ // What the client does with each page it lists before returning it.
+ private final UnaryOperator listed;
+
+ @Nullable private final String cursor;
+
+ private final CallSettings> settings;
+
+ private ListSpec(AsyncClientRequester requester, String method, Class resultType, UnaryOperator listed,
+ @Nullable String cursor, CallSettings> settings) {
+ this.requester = requester;
+ this.method = method;
+ this.resultType = resultType;
+ this.listed = listed;
+ this.cursor = cursor;
+ this.settings = settings;
+ }
+
+ /**
+ * The page to list: the {@code nextCursor} of the previous page, or {@code null}
+ * for the first page.
+ */
+ public ListSpec cursor(@Nullable String cursor) {
+ return new ListSpec<>(this.requester, this.method, this.resultType, this.listed, cursor, this.settings);
+ }
+
+ /**
+ * The timeout of each exchange, instead of the client's.
+ */
+ public ListSpec roundTimeout(Duration roundTimeout) {
+ return with(this.settings.withRoundTimeout(roundTimeout));
+ }
+
+ /**
+ * The bound on the whole call, instead of the client's.
+ */
+ public ListSpec callTimeout(Duration callTimeout) {
+ return with(this.settings.withCallTimeout(callTimeout));
+ }
+
+ /**
+ * Receives the call's progress, instead of the client's listener. The next
+ * notification, and the result, wait for the {@code Mono} it returns.
+ */
+ public ListSpec progress(Function