feat: implement support for SEP-1686 Tasks

[LucaButBoring]

Implements SEP-1686 (Tasks), from the latest specification release.

Motivation and Context

Tasks address several protocol gaps:

1. Avoiding tool splitting anti-patterns - No need to create separate start_tool, get_status, get_result tools; a single task-aware tool handles the full lifecycle
2. Decoupling execution from result retrieval - Clients can dispatch operations immediately and collect results later, without blocking or re-executing if responses are dropped
3. Moving orchestration to host applications - The polling logic lives in the host application/SDK, not in agents that might hallucinate or fail to follow polling contracts

Usage

Server: Defining a Task-Aware Tool

TaskAwareAsyncToolSpecification.builder()
    .name("long-operation")
    .description("A long-running operation")
    .inputSchema(schema)
    // TaskSupportMode.REQUIRED is the default for task-aware tools
    .createTaskHandler((args, extra) -> {
        return extra.createTask()
            .flatMap(task -> {
                startBackgroundWork(task.taskId(), args);
                return Mono.just(CreateTaskResult.builder().task(task).build());
            });
    })
    .build()

Server: Using CreateTaskContext for Lifecycle Management

CreateTaskHandler handler = (args, extra) -> {
    return extra.createTask(opts -> opts.pollInterval(500L)).flatMap(task -> {
        // Start async work that will complete the task later
        doAsyncWork(args)
            .flatMap(result -> extra.completeTask(task.taskId(), result))
            .onErrorResume(e -> extra.failTask(task.taskId(), e.getMessage()))
            .subscribe();

        return Mono.just(McpSchema.CreateTaskResult.builder().task(task).build());
    });
};

TaskSupportMode options:

• REQUIRED (default): Must have task metadata; returns error otherwise
• OPTIONAL: Works with or without task metadata; auto-polling shim provides backward compatibility
• FORBIDDEN: No task support (regular tools)

Client: Streaming API (Recommended)

Drop-in replacement for callTool that handles polling automatically:

client.callToolStream(request)
    .subscribe(msg -> switch(msg) {
        case TaskCreatedMessage<CallToolResult> tc -> log.info("Task: {}", tc.task().taskId());
        case TaskStatusMessage<CallToolResult> ts -> log.info("Status: {}", ts.task().status());
        case ResultMessage<CallToolResult> r -> handleResult(r.result());
        case ErrorMessage<CallToolResult> e -> handleError(e.error());
    });

Client: Task-Based API (For Explicit Control)

For consumers who need custom polling behavior, cancellation logic, or batched task management:

// Create task and get immediate response with task ID
CreateTaskResult created = client.callToolTask(request);
String taskId = created.task().taskId();

// Poll for status updates (with custom logic)
GetTaskResult status = client.getTask(taskId);
while (!status.isTerminal()) {
    Thread.sleep(status.pollInterval());
    status = client.getTask(taskId);
}

// Retrieve final result
CallToolResult result = client.getTaskResult(taskId, new TypeRef<>() {});

// Or cancel if needed
client.cancelTask(taskId);

Similar patterns exist for sampling (createMessageStream / createMessageTask) and elicitation (createElicitationStream / createElicitationTask).

Server: Bidirectional Task Flows

Servers can send task-augmented requests to clients, assuming the client has configured its own TaskStore:

// Server requesting sampling from client with task tracking
exchange.createMessageStream(new CreateMessageRequest(..., taskMetadata, null))
    .subscribe(msg -> ...);

// Server requesting elicitation from client with task tracking
exchange.createElicitationStream(new ElicitRequest(..., taskMetadata, null))
    .subscribe(msg -> ...);

Key Design Decisions

1. Experimental namespace - All task APIs are in io.modelcontextprotocol.experimental.tasks, signaling that the API may change (matches TypeScript/Python SDKs)

2. TaskStore abstraction - Interface for pluggable storage; InMemoryTaskStore provided for development and testing. The originating request (e.g., CallToolRequest) is stored alongside the task, so tool routing can be derived from stored context rather than maintained as separate mapping state.

3. Auto-polling shim - OPTIONAL mode tools work transparently for non-task-aware clients

4. Defense-in-depth session isolation - Session ID required on all TaskStore operations; enforced at both server and storage layers to prevent cross-session task access

   • Passing null for sessionId bypasses validation (single-tenant mode). This is used by McpAsyncClient since clients are inherently single-tenant - there's only one session, so cross-session isolation doesn't apply.

How Has This Been Tested?

• Unit tests
• Client-server integration tests for the typical flows
• Spot-checking compatibility with the TS SDK

Breaking Changes

None

Types of changes

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

Checklist

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

Additional context

Closes #668

This PR also includes a tweak to how 202 Accepted is handled by the client implementation, which was done to handle how the TypeScript server SDK configures its response headers when accepting JSON-RPC responses and notifications from the client - in particular, sending InitializeNotification produced an exception in the Java SDK client before this, which made testing compatibility with the existing TS SDK's Tasks implementation rather difficult.

[He-Pin]

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

[chemicL]

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

[LucaButBoring]

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.

[Randgalt]

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.

[LucaButBoring]

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.

[Randgalt]

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.

[LucaButBoring]

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

[Randgalt]

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?

[LucaButBoring]

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.

[LucaButBoring]

@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();

[LucaButBoring]

Opened #758 to bump the declared protocol version

[Randgalt]

@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.

[Randgalt]

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.

[Randgalt]

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.

[LucaButBoring]

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.

[LucaButBoring]

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

[Randgalt]

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.

[He-Pin]

	public record CallToolResult( // @formatter:off
		@JsonProperty("content") List<Content> content,
		@JsonProperty("isError") Boolean isError,
		@JsonProperty("structuredContent") Object structuredContent,
		@JsonProperty("task") Task task,
		@JsonProperty("_meta") Map<String, Object> meta) implements Result, GetTaskPayloadResult {

I think something like this would be better.

[LucaButBoring]

You mean so that CallToolResult implicitly satisfies CreateTaskResult? It seems unintuitive for SDK consumers to have an ambiguous union like that in method signatures.

[He-Pin]

Yes，I implemented as this, which is simpler

[LucaButBoring]

@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]

@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

[LucaButBoring]

@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).

[Randgalt]

@LucaButBoring Any updates on this?

[LucaButBoring]

Not yet, I'm looking for at least some additional feedback on the implementation approach from maintainers right now.

[Randgalt]

Another month... we're waiting on this PR so we can test our changes.

[amaan75]

Any update on this? Are we waiting for reviews? Is it possible to break it into phases or atleast just merge the toolexecution/taskstore into schemas so we run our own forks for now and later on converge when the reference implementation catches up?

[Kehrlann]

Hey all. We are working on this in the background. We're going to try and land it as soon as possible.

[YousefHaggy]

@LucaButBoring and @Kehrlann, thanks so much for your work on this! Do you have a rough estimate for when this change might land? We're trying to unblock an urgent need for Tasks support on our end. If it's going to take longer than a week, no worries at all, we'll just fork the SDK temporarily. Please let me know, thank you.

[LucaButBoring]

@YousefHaggy Sorry for the repeated delays on this 😓 I discussed this with @chemicL in person during the MCP Dev Summit a couple of weeks ago, and we identified a few (substantial) concrete adjustments to make to this PR, and I'm also working on the stabilization proposal (modelcontextprotocol/modelcontextprotocol#2557) in parallel, which would introduce some breaking changes that would basically immediately stack on top of this (next spec release is tentatively 6/30) - I need to discuss that complication with the Spring folks as well.

Given your degree of urgency I agree that a temporary fork is your most viable option, as this will definitely take at least another week to sort out.

---

For full context, the specific changes @chemicL suggested after we reviewed this together were:

1. Remove the session ID plumbing from TaskStore completely and use the Reactor context object to get the user identity instead.
2. Remove TaskMessageQueue entirely.
   a. For unfulfilled server-to-client requests, store them as a point-in-time map and send them on the SSE stream on every tasks/result request.
   b. For server-to-client notifications, send them eagerly to clients with an ongoing tasks/result SSE stream on a best-effort basis. Notifications sent from a task while no tasks/result stream is active will simply be lost, not queued.
3. Remove all synchronized scopes in favor of copy-on-write data structures; single-threaded Netty executors will throw upon encountering a synchronized scope.

[galm1007]

@LucaButBoring I understand the planned release is for June 30th, but is there an estimation on when this one will be merged? as well as the stabilization proposal?

Thanks for the hard work!