Implement SEP-1686: Tasks

[devcrocod]

This is a tracking issue for implementation of SEP-1686.

Summary

This SEP introduces the task primitive and task ID to support workflow-based operations in MCP, enabling call-now, fetch-later execution patterns across all request types. Tasks are durable state machines with five states (working, input_required, completed, failed, cancelled) that allow requestors to augment requests with task metadata for deferred result retrieval via polling. This addresses critical use cases for long-running operations such as data analysis pipelines, enterprise automation, code migrations, test execution, deep research, and multi-agent systems where immediate responses are impractical and result retention is needed for client-driven status checking.

The Kotlin SDK currently has no support for tasks or async execution patterns. This implementation will require extensive changes including: new task primitive types (Task, CreateTaskResult, TaskStatus enum), task-related request/response types for tasks/get, tasks/result, tasks/list, and tasks/cancel operations, capability declarations in ClientCapabilities and ServerCapabilities structured by request category (tools.call, sampling.createMessage, elicitation.create), optional task field in existing request parameters to support task-augmented execution, metadata handling for io.modelcontextprotocol/related-task associations, TTL-based resource management, status polling mechanisms, DSL builders for task operations, and comprehensive test coverage. The implementation must be backward compatible, allowing receivers to ignore task metadata if not supported, and providing flexibility for receivers to support both traditional immediate execution and task-augmented patterns.

[He-Pin]

Yes, the changeset is quite large, in modelcontextprotocol/java-sdk#671 ,
I just done the schema part, and Kotlin does not support union type too, not sure how it to express the
CallToolResult | CreateTaskResult

[LucaButBoring]

Relaying here from #general-sdk-dev:

There doesn't seem to be a central ticket for all SDK implementations of a particular change, so sharing this here for SEP-1686 -- the following revisions have been merged on top of the base specification PR for tasks:

• Clarify request lifetimes in task diagrams: PR
• Fix capability phrasing in spec: PR
• Remove an incorrectly-added field from notifications/cancelled: PR
• Adjust schema to better-communicate where tasks are valid: PR
• Rename/move annotations.taskHint to execution.taskSupport, tweak its enum values, and change a SHOULD to a MUST for the behavior when this is declared:
  • PR 1
  • PR 2
• GetTask polling clarification: PR
• SSE stream management clarification: PR

The actual functional changes should be limited to taskHint, but the rest should help clarify some details around polling.

To save the trouble of going through each of the above PRs one by one, you can also go to the file on the "Files changed" tab here, searching for docs/specification/draft/basic/utilities/tasks.mdx, and then using the "Display the rich diff" button, as shown:

[LucaButBoring]

One very last change (we're doing a hard cutoff on additional changes here): adding a lastUpdatedAt to the Task object: modelcontextprotocol/modelcontextprotocol#1875

[devcrocod]

@He-Pin

I just done the schema part, and Kotlin does not support union type too, not sure how it to express the
CallToolResult | CreateTaskResult

Сan address this by introducing a common supertype that encapsulates both variants. Then we can handle their serialization and deserialization manually. We’ve used the same approach for the other union types as well

[He-Pin]

another way is using CallToolAuxResult, which contains the task, I checked the current java-sdk's JSONRpcResponse which contains JSONRPCError, so I think put the task inside CallToolResult should be fine too.

What's the shared interface name, CallToolStreamingMessage?