Nice to have this in, the api seems quite the same as typescript sdk

@LucaButBoring Thanks. I'll try to review the PR. In the meantime, please rebase against main as I have fixed the integration tests setup.

Rebased - this is (unfortunately) a very large PR, but I recommend starting with the code related to the key design decisions, and there's also a new integration test (testExternalAsyncApiPattern) which shows a model use case to help understand the high-level flow before digging into the details.

I'm testing with our server implementation.

The protocol version in the initialize request is 2025-06-18. Also, tasks support is empty. I think more documentation may be needed here as I'm missing steps that I've had to come here to get answered.

The protocol version in the initialize request is 2025-06-18.

Will fix this.

Also, tasks support is empty.

That's expected for tool calls from the client - the client only declares a tasks capability when it can accept task creation requests for elicitation or sampling. The server needs to declare a tasks capability when it can accept task creation requests for tool calls.

I'll update the documentation to try and make this more clear.

That's expected for tool calls from the client - the client only declares a tasks capability when it can accept task creation requests for elicitation or sampling. The server needs to declare a tasks capability when it can accept task creation requests for tool calls.

I ran into an issue with this. I've been developing server support for tasks for a while now. I was testing with the current version of the MCP Inspector which reports protocol version 2025-11-25. However, when my server returned Task information in the Tools model for tools/list the Inspector threw an exception. Maybe this is just a bug in the inspector but you could return {} for tasks in ClientCapabilities and still be compatible. But, then, the spec is not clear on this.

The current version of the inspector doesn't support Tasks, that's being worked on here: modelcontextprotocol/inspector#1013

The current version of the inspector doesn't support Tasks, that's being worked on here: modelcontextprotocol/inspector#1013

Yeah, I know. But it still sends protocol version 2025-11-25. Is that a bug?

It is, I'm testing my fix for that right now - looks like #733 added the constant for it but the corresponding constant for the latest version wasn't changed to it.

@Randgalt That requires changing a lot of tests, so I'm considering making that change in a separate PR, is that fine? The protocol version change is technically needed for all of the 11/25 spec features, so I don't think this PR should include it (it should've been done independently first, really). For testing right now, you can declare the supported protocol versions when constructing the transport, like this:

var transport = HttpClientStreamableHttpTransport // or WebClientStreamableHttpTransport
    .builder("http://localhost:" + PORT) // use WebClient.builder().baseUrl() here for WebClientStreamableHttpTransport
    .supportedProtocolVersions(List.of(ProtocolVersions.MCP_2025_11_25))
    .build();

Opened #758 to bump the declared protocol version

@Randgalt That requires changing a lot of tests, so I'm considering making that change in a separate PR, is that fine?

I can't really test this PR without getting the correct protocol from the client. I'll check #758 and see if I can create a merged branch locally to test with.

OK - I pulled both PRs and made a temp branch that has both of them and did some testing. I still don't understand how input_required is supposed to work here. I've tried several different things for the INPUT_REQUIRED step to no avail. When status INPUT_REQUIRED is returned by the client there doesn't appear to be anything I can do. Note, when creating the client I'm calling elicitation(_ -> new McpSchema.ElicitResult(ACCEPT, ImmutableMap.of("firstName", name, "lastName", name + "sky"))).

Here's my code:

        CallToolRequest callToolRequest = CallToolRequest.builder()
                .task(McpSchema.TaskMetadata.builder().ttl(Duration.ofDays(1)).build())
                .name("task")
                .build();
        String taskId = client.callToolTask(callToolRequest).task().taskId();

        boolean done = false;
        while (!done) {
            McpSchema.GetTaskResult task = client.getTask(taskId);
            switch (task.status()) {
                case WORKING -> {}  // do nothing
                case INPUT_REQUIRED -> client.getTaskResult(taskId, new TypeRef<CallToolResult>() {});
                case FAILED, CANCELLED -> fail("Task " + taskId + " should not have failed or been cancelled");
                case COMPLETED -> done = true;
            }

            if (!done) {
                SECONDS.sleep(1);
            }
        }

        CallToolResult callToolResult = client.getTaskResult(taskId, new TypeRef<>() {});

The above stays at INPUT_REQUIRED forever.

I just tried with callToolStream() instead. Our server gets three requests:

1. tasks/get - we return WORKING
2. tasks/get - we return INPUT_REQUIRED
3. tasks/result - we return JsonRpcRequest[jsonrpc=2.0, id=17e9bed8-5420-4ae0-803a-141653492015, method=elicitation/create, params=Optional[ElicitRequestForm[mode=Optional[form], message=Who are you?, requestedSchema={"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["firstName","lastName"]}, meta=Optional[{io.modelcontextprotocol/related-task=69802b8dd9f640bcbe1d127026592b7d}], ttl=OptionalInt.empty]]]

That's it, we don't see the elicit result nor another tasks/get as we would expect. callToolStream() returns with 4 entries. The first 3 are the task and the last is an empty CallToolResult.

Looks like elicitation/sampling aren't wired up to the message queue correctly, I'm adjusting the implementation/tests to address this and properly detect issues with it (this was also an oversight I made in TS at first but the API differences tripped me up when verifying it). Will update once that's resolved.

Should be fixed, now - wired up the queue properly (and trimmed its API surface down a fair bit) and updated the tests to avoid internal blocking, which was masking the issue before

Should be fixed, now - wired up the queue properly (and trimmed its API surface down a fair bit) and updated the tests to avoid internal blocking, which was masking the issue before

It's still behaving somewhat as before. I call callToolStream() in my test and I see:

2026-01-25T10:55:09.921Z	INFO	testing-worker-63	stdout	getTask WORKING
2026-01-25T10:55:24.937Z	INFO	testing-worker-53	stdout	getTask INPUT_REQUIRED
2026-01-25T10:55:24.948Z	INFO	testing-worker-63	stdout	blockUntilTaskResult JsonRpcRequest[jsonrpc=2.0, id=f6109996-fc7b-4a05-af19-63f9fafed7f5, method=elicitation/create, params=Optional[ElicitRequestForm[mode=Optional[form], message=Who are you?, requestedSchema={"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["firstName","lastName"]}, meta=Optional[{io.modelcontextprotocol/related-task=0a9399dd76bb457e87565828a6f69542}], ttl=OptionalInt.empty]]]

Then callToolStream() returns with an empty result.

If I use callToolTask it stays at INPUT_REQUIRED forever.

@Randgalt I pushed a working client/server example to a separate branch (client; server) - how closely does this match your repro? Trying to figure out where our setups diverge so I can diagnose this effectively.

./mvnw exec:java -pl mcp-example-server
./mvnw exec:java -pl mcp-example-client

[CLIENT] Starting callToolStream...
[CLIENT] Message 1: TaskCreatedMessage
[CLIENT]   -> Task created: 1f2ac04b-f512-4948-a6c6-234862820af7
[CLIENT]   -> Initial status: WORKING
[CLIENT]   -> Poll interval: 100ms
[CLIENT] Message 2: TaskStatusMessage
[CLIENT]   -> Task status update: INPUT_REQUIRED
[CLIENT]   -> Status message: Waiting for elicitation
[CLIENT ELICITATION] ========================================
[CLIENT ELICITATION] Received elicitation request #1!
[CLIENT ELICITATION] Message: What is your favorite number?
[CLIENT ELICITATION] Returning response: value=42
[CLIENT ELICITATION] ========================================
[CLIENT] Message 3: ResultMessage
[CLIENT]   -> RESULT RECEIVED!
[CLIENT]   -> Content: [TextContent[annotations=null, text=Got user input via side-channel: {value=42}, meta=null]]

@Randgalt I pushed a working client/server example to a separate branch (client; server) - how closely does this match your repro? Trying to figure out where our setups diverge so I can diagnose this effectively.

This helps, thank you. I found one bug in our server and what I think is a bug in your client. We're expecting _meta to have a io.modelcontextprotocol/related-task entry with the TaskId when the ElicitResult is sent. Your ElicitResult doesn't have a _meta at all. We can't relate it to the corresponding task without this.

https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks#associating-task-related-messages

Updated both branches with the relevant fix - metadata added to all task-related results and notifications

@LucaButBoring we're getting farther, but still not working completely. The elicit request/response loop seems to be working. But, once we receive the ElicitResult we don't get called again and the task times out. Here are the messages we receive:

2026-01-27T14:24:10.819Z	INFO	testing-worker-51	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:10.932Z	INFO	testing-worker-51	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.038Z	INFO	testing-worker-54	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.142Z	INFO	testing-worker-55	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.246Z	INFO	testing-worker-53	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.350Z	INFO	testing-worker-54	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.457Z	INFO	testing-worker-55	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.563Z	INFO	testing-worker-53	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.667Z	INFO	testing-worker-54	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.779Z	INFO	testing-worker-55	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[WORKING]
2026-01-27T14:24:11.882Z	INFO	testing-worker-53	stdout	tasks/get: 297b7a64310e454bbcb6d451c2d726aa Optional[INPUT_REQUIRED]
2026-01-27T14:24:11.888Z	INFO	testing-worker-54	stdout	tasks/result: 297b7a64310e454bbcb6d451c2d726aa
2026-01-27T14:24:11.911Z	INFO	testing-worker-55	stdout	RPC Response: JsonRpcResponse[jsonrpc=2.0, id=115956fc-05a1-40d1-b7ef-55102ad407cc, error=Optional.empty, result=Optional[{action=accept, content={firstName=testListChangeNotifications, lastName=testListChangeNotificationssky}, _meta={io.modelcontextprotocol/related-task=297b7a64310e454bbcb6d451c2d726aa}}]]

Our test code sees the ElicitResponse and then completes the tool/task with our server's Task APIs. But, the MCP client never calls tasks/get again. I'm trying to figure out why, but am having trouble finding it.

Flux/Mono is impossible to debug - awful experience. I'll keep trying.

@LucaButBoring IMO there seem to be a lot of assumptions in this PR. I did some more testing by calling callToolTask() and it stays forever in the INPUT_REQUIRED state. I don't know the Flux/Mono library well enough to debug but I've been trying. What I see is a lot of assumptions about order of operations. I can't place my finger on the exact problem but I think that's where it lies. The server code we've written was based on the docs and this flowchart: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks#task-augmented-tool-call-with-elicitation. I think the MCP client needs to be more of a state machine than assuming things happen in a particular order. My 0.02.

OK - I think I've proven then issue @LucaButBoring

I modified our server so that when the ElicitRequest is sent to the client we leave the connection open and wait to receive the ElicitResult which will cause our test tool to complete the task. I modified our server to send the task's CallToolResult in the same SSE stream that the ElicitRequest was returned in. When I made all these hacks to our server, this PR's client responded correctly and we see callToolStream() return all the responses we expect.

Per the docs as I read them, however, this is not correct. When the client gets the ElicitRequest from the server it should disconnect and start a new stream. The spec flowchart states "Client closes result stream and resumes polling" after it sends the "elicitation response". Our server is expecting this.

That is a valid flow, but not the only valid flow (rather, if the client disconnects polling still works). The relevant part here is from section 5.6:

When a receiver receives a tasks/result request for a task in any other non-terminal status (working or input_required), it MUST block the response until the task reaches a terminal status.

That is a valid flow, but not the only valid flow (rather, if the client disconnects polling still works). The relevant part here is from section 5.6:

When a receiver receives a tasks/result request for a task in any other non-terminal status (working or input_required), it MUST block the response until the task reaches a terminal status.

Ok. If so, that’s unfortunate. I’ll see what can be done to improve the spec. But I’ll adjust our server accordingly and get back to you.

Definitely room for discussion on this, and the incoming Transports WG proposals may very well change this - I'll be discussing this with them in the meeting tomorrow.

OK - at long last everything is working. Thanks for all your work on this.

@LucaButBoring I apologize, I promised I'd review this PR and started doing that but had to prioritize the conformance tests and had to take a pause. I will get back to it after I'm back from PTO in a week. My quick feedback for now is that the implementation is quite invasive and scattered in the core McpAsyncServer class and it would be a good opportunity to look at #578 to provide better encapsulation of this feature. I'll do a more thorough review later.

There are at least a few reasons why it's as invasive as it is right now, off the top of my head:

• Client response routing to tool handlers: In regular tools, you can make the assumption that messages can be routed to and from a work unit coupled to a request, while with tasks we're explicitly stepping outside that model, which required changes to the core processing flows
• Late delivery of server requests and notifications: Generally, when a server dispatches an elicitation/sampling request or a notification, that message is delivered immediately to the client (potentially getting held in the SSE event store first for resumability). In tasks, we need a decoupled queue to route messages based on the task ID instead, as those messages get side-channeled through the response stream on tasks/result.
• Task requests get back a CreateTaskResult, not a regular result for the request type, so at a minimum they need new request methods if we want to avoid breaking changes (or deal with a bunch of null fields if we just add task properties to things).

With that said, I'm open to overhauling this entirely if it's possible to encapsulate this in a repository, I just don't currently see how that could be done without making invasive changes anyways (tasks don't exactly satisfy AsyncToolSpecification, for example).

New test failure appears to be existing flakiness - I haven't yet been able to reproduce it.

@chemicL The TS SDK is refactoring their implementation of Tasks in modelcontextprotocol/typescript-sdk#1449, and I think their new approach is slightly better about decoupling logic from the core message exchange - I'm going to try to refactor this to extract a TaskManager like they have as a starting point.

@chemicL Updated, how does McpAsyncServer look now? I tried to trim as much out of it as possible, pushing most of the lifecycle logic into ServerTaskToolHandler instead (and about the same for the client side).