Repository navigation
Description
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.
-
- 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.
-
- 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:
- Polling mechanisms (feature: Async support without using Resource #650, feature: async support #700, feature: Async support using Resource #651)
- Resource-based status tracking (fix: add status field in Resource class and Resource as a return type in CallToolResult #549, feature: Async support using Resource #651)
- Async tool calls with rejoin capabilities (feature: async tool call with join for disconnected clients and progress resources #617)
2. Transport-Agnostic Solutions
Several proposals aim to create solutions that work across different transport protocols:
- SEP-975: Transport-agnostic resumable requests #925 & SEP-975: Transport-agnostic resumable requests #975: SEP-003 for transport-agnostic resumable requests
- Proposal: Transport-agnostic resumable streams #543: Transport-agnostic resumable streams
3. Progress Tracking
Multiple proposals address the need for better progress tracking:
- Support progress notification trees for task fanout #929: Progress notification trees for concurrent subtasks
- feature: async tool call with join for disconnected clients and progress resources #617: Progress resources during task execution
- Various PRs include progress tracking as part of their async implementations
4. Connection Resilience
A common concern is handling client disconnections during long-running operations:
- feature: async tool call with join for disconnected clients and progress resources #617: Allows clients to rejoin in-progress tasks
- SEP-975: Transport-agnostic resumable requests #925/SEP-975: Transport-agnostic resumable requests #975: Resume requests after disconnection
- Proposal: Transport-agnostic resumable streams #543: Resumable streams proposal
Related Issues and Cross-References
- Webhooks for Operations in MCP #523: Async communication
- Supporting client callbacks/webhooks with HTTP transport #266: Webhook support
- Add Event Subscription and Publishing Support toMCP #179: Event Subscription and Publishing Support
- Proposal: Events - new protocol element Event - list-topics, subscribe, unsubscribe, list-events #611: Events - new protocol element Event
- Add stateless, streaming and async tool annotations #489: Tool Annotations
- feat: add support for partial results and streaming responses #776, [feat] Introduce partial results as part of progress notifications #383, Stateful stdio servers present a safety hazard for multi-conversation clients like Claude Desktop #823: Various async-related discussions
- Feature/resource progress python-sdk#800, Feature/617 async call tools python-sdk#866: Python SDK implementation references
Activity
victordibia commentedon Jul 16, 2025
Thanks for the collection here @ihrpr .
Is there a case for a theme on "partial results"?
I say this because:
Happy to hear thoughts.
Joffref commentedon Jul 17, 2025
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
notificationConfigobject in the tool call — or atrigger, as proposed in #593 — is the second-best path toward complete async handling, regardless of how the server is deployed.Joffref commentedon Jul 17, 2025
Just a heads up, I have opened #992 regarding my message from yesterday.
ihrpr commentedon Jul 24, 2025
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
call_async_requestin addition tocall_toolProposal 2: Resumable Requests
Link: Resumable requests #925
Proposal 3: Minimal Changes Approach (Google)
Link: Cursors and resume tokens #1003
Documentation: Design doc
Major Concerns Raised:
1. Session Management Confusion
Key issues identified:
2. Resumability as New Concept vs. Transport Improvements
A significant concern was raised that the resumability proposal (Proposal 2) may be problematic because:
Counter-arguments included:
3. Transport Agnosticism Debate
Key Technical Debates:
Action Items:
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.
[-][notes] Long running tools[/-][+][notes] Long running tools/ async tools/ resumability[/+]TristonianJones commentedon Jul 25, 2025
@ihrpr I've moved
resumeTokenandnextResumeTokenout of the "sidecar" and into the payload in #1003. Functionally, the approach doesn't really change, so I'm happy to move it.davemssavage commentedon Jul 28, 2025
@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.
davemssavage commentedon Aug 16, 2025
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.
jonathanhefner commentedon Aug 16, 2025
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.)
davemssavage commentedon Aug 16, 2025
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:
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.
jonathanhefner commentedon Aug 17, 2025
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/resumePolicynotification.davemssavage commentedon Aug 17, 2025
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:
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:
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.
mikekistler commentedon Aug 17, 2025
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?
davemssavage commentedon Aug 18, 2025
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.
jonathanhefner commentedon Aug 18, 2025
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.
davemssavage commentedon Aug 18, 2025
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.
davemssavage commentedon Aug 24, 2025
(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.