Skip to content

[notes] Long running tools/ async tools/ resumability #982

Closed

Description

@ihrpr

This issue is just a note on all the proposals for Long Running Tools and related topics. It is used for tracking only and notes from the steering committee will be shared here.

If any related proposal/discussion/PR/Issue is missing, please comment.


Transport-Agnostic Solutions

  • SEP-975: Transport-agnostic resumable requests #925

    • Author: Jonathan Hefner & Connor Peet
    • Summary: Introduces a mechanism for resuming requests after disconnections across different transport protocols. Key features: clients and servers can disconnect and reconnect without losing progress, servers can communicate expire-after-disconnect timeouts, clients can check request status after disconnect, works across transport types (HTTP, WebSocket, stdio, etc.). Addresses limitations of resumability in Streamable HTTP transport and enables robust handling of long-running requests.
  • SEP-975: Transport-agnostic resumable requests #975

    • Author: Jonathan Hefner & Connor Peet
    • Summary: Formal SEP for transport-agnostic resumable requests mechanism allowing disconnect/reconnect without losing progress. Servers communicate expire-after-disconnect timeouts, clients check request status after disconnect without fetching undelivered messages. Works across HTTP, WebSocket, stdio, etc. Introduces methods like requests/resume and requests/getStatus.
  • Proposal: Transport-agnostic resumable streams #543

    • Author: Jonathan Hefner
    • Summary: Proposal for generalized, transport-independent mechanism for resumable streams in MCP. Key features: stream/begin JSON-RPC notification to start stream with unique ID, stream/end notification to mark completion, stream/resume notification to reconnect, stream/poll request to check status. Aims to improve stream handling across different transport mechanisms, providing more flexibility and reliability for tool interactions.

New Protocol Primitives

  • feature: Async support without using Resource #650

    • Author: bzsurbhi
    • Summary: Implements a basic polling mechanism for long-running operations. The proposed workflow includes: Client sends CallToolAsyncRequest → Server responds with CallToolAsyncResult → Client polls server with CheckToolAsyncStatusRequest → Server returns status → When status is ACTIVE, client retrieves final result. Also adds listToolsAsync call capability.
  • feature: async support #700

    • Author: bzsurbhi
    • Summary: Adds support for long-running asynchronous operations with workflow: Client → Server: CallToolAsyncRequest, Server → Client: CallToolAsyncResult → AsyncOperation, Client → Server (Poll): GetOperationRequest, Server → Client: GetOperationResult with operation status and resourceUri. Includes polling mechanism to check operation status and retrieve results once complete.
  • feature: async tool call with join for disconnected clients and progress resources #617

    • Author: davemssavage
    • Summary: Extends MCP to support long-running async tasks with key features: allows clients to submit async tool call requests, enables clients to rejoin in-progress async tasks after disconnection, provides progress notifications and resources during task execution, maintains backwards compatibility. Addresses the limitation that "long running async tasks on the server rely on a continuous connection to the server, also they have limited options for notification of progress."
  • Support progress notification trees for task fanout #929

    • Author: Jonathan Hefner
    • Summary: Proposal to improve progress notifications by allowing representation of concurrent subtasks. Suggests adding a notifications/progress/createTracker method that would: allow declaration of new progressToken, support parent-child relationships between progress trackers, enable tools to forward progress notifications from subtasks. Provides flexibility for tools managing complex workflows with nested/concurrent task progress tracking.
  • Cursors and Resume Tokens

    • Author:
    • Summary: Introduces resumeToken and nextResumeToken fields for handling long-running operations that extend beyond pagination. Addresses resuming operations whose parameters don't change between invocations but results may change over time. Supports database queries, eventually consistent systems, and human-in-the-loop workflows. The resumeToken (caller-provided) indicates a stateful/resumable operation, while nextResumeToken (receiver-provided) enables multiple call/result pairs indicating stages of completion. Works across connections and complements existing progress token mechanisms.

Resource-Based Approaches

  • fix: add status field in Resource class and Resource as a return type in CallToolResult #549

    • Author: bzsurbhi
    • Summary: Enhances support for long-running operations by implementing a Resource-based polling mechanism. Adds a status field to the Resource class and allows Resource as a return type in CallToolResult. The discussion evolved into exploring alternative approaches including Promise-based approach, AsyncOperation class, and task reference system. Multiple participants explored various approaches to handling long-running asynchronous operations.
  • feature: Async support using Resource #651

    • Author: bzsurbhi
    • Summary: Introduces async support utilizing Resource and its subscribe/notify features. Workflow: Client sends CallToolAsyncRequest → Server responds with CallToolAsyncResult (AsyncOperation) → Client polls with GetOperationRequest → Server returns GetOperationResult with resource URI and status. Enables partial results through ResourceUpdated notifications, allows hosts to disconnect/reconnect to check status, provides flexible async tool call management.
  • Asynchronous operations in MCP #491

    • Author: bzsurbhi
    • Summary: Comprehensive proposal for supporting long-running async operations with features: marking tools as supporting async execution, creating async resources to track operation status, allowing clients to subscribe and monitor operations, providing mechanisms for progress updates, result retrieval, and cancellation. Includes detailed specifications for AsyncResource class, Tool/ToolManager extensions, new API formats, and implementation examples.

Problem Space & Requirements

  • Defining the problem space for asynchronous tool execution #843

    • Author: Joffref
    • Summary: Explores challenges with current request/response model focusing on four key problems: 1) Unresponsive clients during long-running tasks, 2) Inefficiencies in agentic systems, 3) Incompatibility with long-running or indefinite jobs, 4) Lack of state certainty after client disconnection. Discussion explores potential solutions including resource pointers, subscriptions, and notification mechanisms while maintaining client responsiveness.
  • [RFC] Long Running Task/Job/Async handling modelcontextprotocol-community/working-groups#30

    • Author: cploujoux
    • Summary: RFC discussing challenges with handling long-running tasks in MCP including: connection persistence when using SSE for long periods, client disconnection handling to ensure task continuation, tracking progress and state of long-running operations, potential event system and webhook implementation. Links to multiple related proposals and has been moved to official Standards Track for review.

Summary Documents

  • Google Doc Summary
    • Summary: Summary document consolidating async/long-running task proposals

Note on Webhook Approaches

While not included in active proposals (closed PR #593 proposed webhook support), the webhook pattern has been discussed as a potential solution for async communication, particularly in modelcontextprotocol-community/working-groups#30. The approach was closed in favor of more generalized trigger mechanisms.

Themes

(AI generated summaries)

1. Asynchronous Operations

Most proposals focus on handling long-running operations that may take hours or days to complete. The main approaches include:

2. Transport-Agnostic Solutions

Several proposals aim to create solutions that work across different transport protocols:

3. Progress Tracking

Multiple proposals address the need for better progress tracking:

4. Connection Resilience

A common concern is handling client disconnections during long-running operations:

Related Issues and Cross-References

Activity

  1. added
    notesNotes from meetings and discussions. Used for tracking purposes only, no action is needed.
    on Jul 16, 2025
  2. victordibia commented on Jul 16, 2025

    @victordibia

    Thanks for the collection here @ihrpr .
    Is there a case for a theme on "partial results"?

    I say this because:

    Happy to hear thoughts.

  3. Joffref commented on Jul 17, 2025

    @Joffref
    Contributor

    Thank you very much for this document, @ihrpr. I know how messy this topic currently is and how many discussions we've had around it.

    What I’m seeing is that transport-agnostic solutions are the most likely to succeed and become the primary way to handle async in MCP — thank you for your work on this, @jonathanhefner and @connor4312!

    That said, I think we can all agree this only addresses part of the problem. The main limitation is that it relies heavily on the client to maintain state and resume tool calls, which isn't feasible in some environments — serverless, for instance. In those cases, we may also want the notification and result to be sent somewhere else entirely.

    I'm still uncertain about resources. While I see the elegance and simplicity of the approach, it overlaps quite a bit with previously discussed solutions. I also think it could introduce significant complexity when dealing with multi-tenant MCP deployments.

    Many of the other proposals are complex and feel intuitive within the MCP context. Personally, I still believe a simple notificationConfig object in the tool call — or a trigger, as proposed in #593 — is the second-best path toward complete async handling, regardless of how the server is deployed.

  4. Joffref commented on Jul 17, 2025

    @Joffref
    Contributor

    Just a heads up, I have opened #992 regarding my message from yesterday.

  5. ihrpr commented on Jul 24, 2025

    @ihrpr
    ContributorAuthor

    Summary of Notes: "MCP: agents wg catch-up" - July 23, 2025

    This meeting of the MCP (Model Context Protocol) agents working group focused on discussing proposals for async/long-running task support. The meeting included participants from AWS, Google, Microsoft, OpenAI, VS Code, and other organizations.

    Three Main Proposals Discussed:

    Proposal 1: Non-Resource Based Approach (AWS)

    Link: Feature: Async support without using Resource #650
    Documentation: Async approaches

    • Core Concept: Introduces new request type call_async_request in addition to call_tool
    • Mechanism: Server returns result with token; client polls for status
    • Pros:
      • Clean separation between tools and resources
      • Clean separation between tools and async tools
      • Backwards compatible (new endpoint doesn't break existing clients)
      • Supports structured content (unlike current resources)
    • Cons:
      • Doesn't leverage existing resource subscription/notification features
      • Adds complexity to the spec
      • Old clients cannot use these new async tools

    Proposal 2: Resumable Requests

    Link: Resumable requests #925

    • Core Concept: Transport-agnostic approach for all call types, not just tools
    • Mechanism: Uses resume policy notifications with tokens for disconnection/reconnection
    • Pros:
      • Works for all types of calls (future-proof for A2A flows)
      • Handles disconnection gracefully
      • Server decides on async operation based on client capabilities
    • Cons:
      • Doesn't provide static output consumable by multiple consumers
      • Doesn't follow traditional async patterns (no explicit task concept)
      • Adds new layer instead of fixing transport resumability limitations

    Proposal 3: Minimal Changes Approach (Google)

    Link: Cursors and resume tokens #1003
    Documentation: Design doc

    • Core Concept: Fits existing async API patterns into MCP with minimal changes
    • Mechanism: Uses existing tool payload with extra metadata/tokens
    • Pros:
      • Minimal protocol changes
      • Supports both pagination and long-running operations
      • Aligns with industry-standard async patterns
    • Cons:
      • Places burden on client to manage tokens
      • May fetch large results when only status is needed
      • Token in "sidecar" approach needs clearer justification

    Major Concerns Raised:

    1. Session Management Confusion

    Key issues identified:

    • Fundamental confusion about session lifetimes and tool call persistence
    • No clear understanding of what happens to tool calls when sessions end
    • Unclear if sessions can be resumed after closing
    • Different SDKs currently implement different behaviors
    • Session definition exists in protocol but applicability varies across transports

    2. Resumability as New Concept vs. Transport Improvements

    A significant concern was raised that the resumability proposal (Proposal 2) may be problematic because:

    • It introduces a new layered concept instead of fixing existing transport limitations
    • Current specification already supports this functionality through session IDs and event resumability
    • Suggestion to fix transport specification limitations directly rather than compensating with new abstractions
    • The proposal essentially recreates existing session management functionality

    Counter-arguments included:

    • Initial attempts to fix transport issues led to conclusion that a unified approach was better
    • Approach could extend to all transports, including standard IO
    • Servers without session support could still benefit

    3. Transport Agnosticism Debate

    • Questions about calling proposals "transport agnostic" when they deal with transport-specific concerns
    • Need to avoid leaking transport-level concerns into the protocol
    • Balance between handling disconnections and maintaining clean abstractions

    Key Technical Debates:

    1. Scope Beyond Tools:
    • Need for async support beyond just tool calls emphasized
    • Future A2A flows will require broader async capabilities
    • Should design for composable, long-running tasks not tied to single calls
    1. Backwards Compatibility Interpretations:
    • Schema compatibility vs. functional compatibility
    • Whether old clients should be able to use new async features
    • Trade-offs between clean design and backwards compatibility
    1. Unified vs. Separate Async Tools:
    • Whether async should be a distinct tool type or integrated
    • Server vs. client responsibility for choosing sync/async behavior
    • Impact on server implementers (e.g., load balancer concerns)

    Action Items:

    1. Publish meeting notes and attach to GitHub issues
    2. Continue discussions on PRs and Discord
    3. Meet again in 2 weeks due to importance of topic
    4. Clarify rationale for token side-channel approach in Proposal 3
    5. All participants to review proposals thoroughly before next meeting
    6. Move Support progress notification trees for task fanout #929 to next session (not reviewed in this meeting)
    7. Proposal for triggers were not discussed during this session, those should be added to the next session

    The meeting revealed fundamental philosophical differences about whether async should be a protocol-level concept, how to handle backwards compatibility, and whether to fix existing transport limitations or create new abstractions. The session management and resumability concerns were particularly important topics of discussion, with thoughtful arguments for improving existing mechanisms.

  6. changed the title [-][notes] Long running tools[/-] [+][notes] Long running tools/ async tools/ resumability[/+] on Jul 24, 2025
  7. TristonianJones commented on Jul 25, 2025

    @TristonianJones

    @ihrpr I've moved resumeToken and nextResumeToken out of the "sidecar" and into the payload in #1003. Functionally, the approach doesn't really change, so I'm happy to move it.

  8. davemssavage commented on Jul 28, 2025

    @davemssavage

    @ihrpr I've been exploring another approach and I think #617 is no longer required, essentially with a bit of extra work on the client side it's possible to expose the request id and use the existing protocol messages to achieve the goals I was looking for on 617. Namely that a client can disconnect and reconnect later.

    modelcontextprotocol/python-sdk#1209 shows how this can be implemented using the python sdk.

  9. davemssavage commented on Aug 16, 2025

    @davemssavage

    @ihrpr I've been exploring another approach and I think #617 is no longer required, essentially with a bit of extra work on the client side it's possible to expose the request id and use the existing protocol messages to achieve the goals I was looking for on 617. Namely that a client can disconnect and reconnect later.

    modelcontextprotocol/python-sdk#1209 shows how this can be implemented using the python sdk.

    Further testing of the above python patch indicates that there is a non-trivial sequence of events to enable a call_tool to be started and then later (re) joined. In summary as things stand with the above patch the python server must send at least one notification associated with the call tool request back to the client in order for the client start_call_tool method to return the request_id.

    The simplest non protocol breaking change I have found to fix this is to emit a zero progress notification at the start of any long running tool call on the server, that way the client has an sse event id to resume. This is a little opaque however and relies on the client requesting progress for this to work - though it could be argued that a client that submits a long running tool call without progress is potentially an anti-pattern.

    A cleaner approach may be to add a new protocol message that acts as an acknowledgement notification from the server to the client it has received the call tool request, this would be in addtion to any progress notifications. This however undermines the idea presented in this patch that long running tool calls do not need any change to the protocol specification.

  10. jonathanhefner commented on Aug 16, 2025

    @jonathanhefner
    Member

    Further testing of the above python patch indicates that there is a non-trivial sequence of events to enable a call_tool to be started and then later (re) joined. In summary as things stand with the above patch the python server must send at least one notification associated with the call tool request back to the client in order for the client start_call_tool method to return the request_id.

    The simplest non protocol breaking change I have found to fix this is to emit a zero progress notification at the start of any long running tool call on the server, that way the client has an sse event id to resume. This is a little opaque however and relies on the client requesting progress for this to work - though it could be argued that a client that submits a long running tool call without progress is potentially an anti-pattern.

    Your observation is correct! I mentioned it in the first bullet point in the "Motivation" section of SEP #975. 😃

    Since #975 was rejected, I have submitted SEP #1335 in order to address the issue. (See the first bullet points in the "Motivation" and "Specification" sections.)

  11. davemssavage commented on Aug 16, 2025

    @davemssavage

    Your observation is correct! I mentioned it in the first bullet point in the "Motivation" section of SEP #975. 😃

    Since #975 was rejected, I have submitted SEP #1335 in order to address the issue. (See the first bullet points in the "Motivation" and "Specification" sections.)

    Yep I think I'm finally coming back around to the idea that the only missing piece of the protocol in it's current form for long running requests is how to issue an sse id consistently. The rest can be solved by client side libraries as demonstrated by the python code in #1209.

    I note you state in #1335:

    Servers must send an initial event immediately after starting the SSE stream. The event data must be a JSON object. It must not contain values related to the RPC result, but it may contain other information."

    Would this be consistent with the idea of sending a ProgressNotification with zero progress to boot strap the request id?

    I will concede it does feel a bit hacky to send a progress notification when one has not been requested via a callback but I think it is at least semantically correct, doesn't involve any new message types and I would expect any sdks to handle a notification with no preregistered callback gracefully.

  12. jonathanhefner commented on Aug 17, 2025

    @jonathanhefner
    Member

    Would this be consistent with the idea of sending a ProgressNotification with zero progress to boot strap the request id?

    Yes, sending a progress notification would provide the client with an event ID. That is one of the reasons that #975 proposed immediately sending a notifications/requests/resumePolicy notification.

  13. davemssavage commented on Aug 17, 2025

    @davemssavage

    Would this be consistent with the idea of sending a ProgressNotification with zero progress to boot strap the request id?

    Yes, sending a progress notification would provide the client with an event ID. That is one of the reasons that #975 proposed immediately sending a notifications/requests/resumePolicy notification.

    Ok great, I think having been round the houses a bit I'm now on the same page as you, the protocol is already able to support async, with caveat (below), the problem is for the clients to expose this (one potential solution 1209).

    The caveat to the above is that there is a requirement for a tool to send at least one message to allow this to work reliably. For short lived requests any blocking on the client will be resolved by the CallToolResult. However for long lived requests the client cannot resume until at least one event is received from the server. A client cannot know that the server will be well behaved as the protocol does not suggest/mandate an event in this scenario.

    To resolve the above I think there are two options:

    1. Leave this to tool implementors, i.e. document that long lived tools requests SHOULD/MUST send a progress event at the earliest opportunity or,
    2. it could be pushed down into protocol layer such that call_tool_request has an associated call_tool_ack notification that complements the call_tool_result.

    In either scenario client side code must be developed such that it does not rely on an event as this cannot be guaranteed in a distributed environment, that is it should deal with no event gracefully with timeouts etc (this is current gap in 1209 which I will patch shortly).

    In terms of downsides I can think of of the top of my head:

    • For the first
      • it relies on tool implementers to read the docs leading to inevitable gaps
    • For the second
      • it is more complex and results in an extra message even when a request is short lived.

    Note for option 1 I discovered that the python client does not set a related_request_id for progress notifications here. I am unclear at present if this is a requirement in the protocol and therefore an oversite in the python implementation. Regardless it is required for the python client to associate the progress notification with the request to retrieve the sse.id so this may also be needed as an addition to the protocol specification if this route is chosen.

  14. mikekistler commented on Aug 17, 2025

    @mikekistler

    I will concede it does feel a bit hacky to send a progress notification when one has not been requested

    If the client did not request progress notifications, what progress token would be sent in the notification, and how would the client be able to correlate this back to the tool call?

  15. davemssavage commented on Aug 18, 2025

    @davemssavage

    I will concede it does feel a bit hacky to send a progress notification when one has not been requested

    If the client did not request progress notifications, what progress token would be sent in the notification, and how would the client be able to correlate this back to the tool call?

    So yes this is where it gets messy, as it stands I interpret the spec says a server is not allowed to send a token the client is not expecting.

    As noted in my previous post it does seem like an anti-pattern to start a long lived request without requesting progress. Therefore this could be tackled in the protocol by linking resumeablity with progress updates more explicitly. Perhaps only guaranteeing resumption of a previous request if a client has received a progress update (even a zero progress update) - implying the client must request progress and have received an update to resume?

    An alternative approach which I think is definitely tending towards a hack would be a relaxation of the protocol where servers are allowed to send unsolicited progress notifications (probably use a reserved token for this case). Whist a breaking change and with a fair degree of code smell, I would expect it to be a minimal impact for clients to ignore a token that doesn't map to local progress token and defensive coding would probably encourage this behaviour anyway.

    Regarding correlation the sse.id and resumption behaviour is triggered by the related_request_id in the python client and not the progress_token so assuming this is common to other clients (though I haven't done an indepth analysis of this) the progress notification is simply being used as an existing semantically convenient barer message to transfer the sse.id back to the client so it can resume later.

    FWIW I think I favour the first option of linking resumability with progress rather than allowing an unsolicited progress update. I'm struggling to think of a use case where a client would submit a tool call that is potentially going to take minutes/hours/(days?) without also requesting progress updates and conveniently those progress updates also provide the sse.id to allow it to resume.

  16. jonathanhefner commented on Aug 18, 2025

    @jonathanhefner
    Member

    An alternative approach which I think is definitely tending towards a hack would be a relaxation of the protocol where servers are allowed to send unsolicited progress notifications (probably use a reserved token for this case). Whist a breaking change and with a fair degree of code smell, I would expect it to be a minimal impact for clients to ignore a token that doesn't map to local progress token and defensive coding would probably encourage this behaviour anyway.

    Please see #1335, which addresses the issue without sending a progress notification. In particular, please see the first bullet points in the "Motivation" and "Specification" sections.

    The idea is that the Streamable HTTP transport transparently sends an event immediately after the SSE stream begins. The event data is a JSON object. The JSON object may be empty, or may contain information that isn't directly related to the RPC result.

  17. davemssavage commented on Aug 18, 2025

    @davemssavage

    The idea is that the Streamable HTTP transport transparently sends an event immediately after the SSE stream begins. The event data is a JSON object. The JSON object may be empty, or may contain information that isn't directly related to the RPC result.

    So this does feel a bit 'magic' to be sending an empty event data and you note that it may have adverse effects on clients e.g. breaking protocol changes - as previous debates I do agree this can be handled via protocol negotiation but this does feel a little unnessary in this case.

    IMO progress is intrinsically linked to resumability so resuming something that the server has reported is in progress seems natural and the client having to guess if it can resume despite no indication that it is in progress also feels a little odd. Also requiring a client to request progress on long running tasks also seems natural as why submit a long running task that it doesn't want to know when it's done. Finally it allows the server to tell the client that progress has been made so in the disconnected client scenario it allows it to reconnect to get other info such as log events etc.

    However as it will clearly work and in absense of anyone else clamoring for progress notifications as the sse.id bearer if this is what actually allows this topic to (ironically) make progress I could get behind #1335. If this is indeed the way forward help in getting this implemented in the python sdk (either by reviewing/accepting 1209 with modifications to implement #1335 or another similar patch from another contributor would be great as keeping that up to date with the main branch is getting a bit laborious.

  18. davemssavage commented on Aug 24, 2025

    @davemssavage

    ...If this is indeed the way forward help in getting this implemented in the python sdk (either by reviewing/accepting 1209 ... or another similar patch from another contributor would be great as keeping that up to date with the main branch is getting a bit laborious.

    (facepalm) the patch last week to handle request_call_tool timeout broke the build on 1209 posting this as I've now fixed the tests in case anyone is interested in following up on this.

  19. locked and limited conversation to collaborators on Nov 2, 2025
  20. converted this issue into a discussion #1758 on Nov 2, 2025
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

    notesNotes from meetings and discussions. Used for tracking purposes only, no action is needed.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions