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 TaskContext for Lifecycle Management

TaskContext ctx = extra.createTaskContext(task);
ctx.updateStatus("Processing batch 1 of 10");
ctx.isCancelled().flatMap(cancelled -> {
    if (cancelled) return ctx.fail("Cancelled by user");
    return doWork().then(ctx.complete(result));
});

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]

Shouldn't this be ClientTaskPayloadResult? Regardless, there is no current way to get the input_required request from the client for a task.

[LucaButBoring]

This is the client, so when it calls tasks/result, it will only receive the appropriate server message for the task (currently only CallToolResult).

The input_required-bound request happens asynchronously relative to this but (with SSE) requires the client to invoke tasks/result first.

[LucaButBoring]

There's a lengthy (and admittedly hard to parse) note on the input_required status in the spec explaining the side-channeling here: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks#input-required-status

[Randgalt]

Why have the typeRef? There's only 1 possible result type.

[LucaButBoring]

Mostly for consistency with the server version of this interface, and so that we don't need to make a breaking change if (I expect "when") we add more supported client->server methods for Tasks.

[Randgalt]

same as above

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