Skip to content

Implement SEP-1686: Tasks #421

Closed
Enhancement
3 of 3 issues completed
#844
#566
Closed
Implement SEP-1686: Tasks#421
Enhancement
3 of 3 issues completed
#844
#566
Labels
P2Moderate issues, valuable feature requestsapiPublic API changesenhancementNew feature or requestneeds confirmationUnclear if still relevant

Description

@devcrocod
devcrocod
opened on Nov 20, 2025

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.

  • Add types:
    • Task
    • TaskStatus
    • TaskMetadata
    • RelatedTaskMetadata
    • CreateTaskResult
    • ListTasksRequest
    • ListTasksResult
    • GetTaskRequest
    • GetTaskResult
    • GetTaskPayloadRequest
    • GetTaskPayloadResult
    • CancelTaskRequest
    • CancelTaskResult
    • TaskStatusNotification
    • TaskStatusNotificationParams
  • Add methods to Method.Defined.
  • Update serializers and DSL builders.

Activity

  1. devcrocod
    added this to 2025-11-25 Implementationon Nov 20, 2025
  2. devcrocod
    added
    enhancementNew feature or request
    on Nov 20, 2025
  3. devcrocod
    added the
    Enhancement
    issue type on Nov 20, 2025

  4. He-Pin commented on Nov 21, 2025

    @He-Pin
    He-Pin
    on Nov 21, 2025

    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

  5. LucaButBoring commented on Nov 21, 2025

    @LucaButBoring
    LucaButBoring
    on Nov 21, 2025

    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:
    • 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:
    Image

  6. LucaButBoring commented on Nov 24, 2025

    @LucaButBoring
    LucaButBoring
    on Nov 24, 2025

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

  7. devcrocod commented on Nov 25, 2025

    @devcrocod
    devcrocod
    on Nov 25, 2025
    ContributorAuthor

    @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

  8. He-Pin commented on Nov 25, 2025

    @He-Pin
    He-Pin
    on Nov 25, 2025

    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?

  9. devcrocod
    marked this as blocked on Feb 19, 2026
  10. devcrocod
    marked this as blocking on Feb 19, 2026
  11. devcrocod
    added a commit that references this issue on Mar 20, 2026

    feat: add tasks models (#566)

    fd3a858

  12. kpavlov commented on Apr 2, 2026

    @kpavlov
    kpavlov
    on Apr 2, 2026
    Contributor

    See also #567

  13. devcrocod
    added
    P2Moderate issues, valuable feature requests
    needs confirmationUnclear if still relevant
    apiPublic API changes
    on Apr 8, 2026
  14. devcrocod
    added a parent issue on Apr 8, 2026
  15. devcrocod
    added sub-issues on Apr 13, 2026
  16. devcrocod
    added a commit that references this issue on Jun 30, 2026

    feat: SEP-1686 Tasks (#844)

    57e546d
  17. devcrocod
    closed this as completedon Jun 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Moderate issues, valuable feature requestsapiPublic API changesenhancementNew feature or requestneeds confirmationUnclear if still relevant

    Type

    Enhancement

    Projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions