On this page
MCP Tasks give a long-running operation a durable handle so a client can check progress, provide requested input and retrieve the eventual result. Use the extension when a tool operation cannot sensibly finish within an ordinary request. A returned task handle means work has been accepted; it does not mean that work has completed.
The current Tasks overview describes the extension's creation, polling, input and cancellation flow. If you implemented an earlier experimental Tasks API, check the current specification before reusing its methods or state assumptions.
Separate protocol state from application work
Consider an import that reads a supplier CSV, validates its rows and saves acceptable records. The tool request may return quickly, while parsing and review continue elsewhere. A task ID lets the user return to that operation without submitting the same import again.
The application still needs to store the file reference, current progress, validation results and saved output. A stateless request protocol does not remove this application state. It changes how a client reaches the work; it does not make the work itself disappear between requests.
The July 2026 specification release-candidate article explains the move from experimental core Tasks to an extension. Use that article for migration context and the current extension documentation for implementation. A release-candidate description alone is not a substitute for the protocol version that your client and server actually support.
Map every visible state to evidence
Use an explicit state mapping in the app. The following table applies the documented task states to an illustrative import workflow. It is a design example, not a wire-format specification.
| Task state | Import example | What the user can do |
|---|---|---|
| working | The worker is validating rows | Check the saved progress record |
| input_required | The file contains an ambiguous column | Review the question and provide input |
| completed | A final result is available | Inspect accepted and rejected rows |
| failed | The operation ended with an error | Read the failure before deciding to retry |
| cancelled | The operation ended after cancellation | Inspect any application-side effects |
The UI should distinguish “cancel requested” from a terminal cancelled state. The Tasks documentation describes cancellation as cooperative. The application may need to finish a safe checkpoint or report that some work was already committed. A button click is evidence of user intent, not evidence that all processing has stopped.
Likewise, distinguish validation completion from import completion. A file can pass parsing while a database write fails. If your tool promises saved supplier records, the final result should identify those saved records and the checks performed. Do not mark the task complete merely because a worker process exited successfully.
Create one job for one intended operation
Plan for a client that loses the initial response. It may be unsure whether the server accepted the work. Your application's operation identity should let it reconcile that uncertainty instead of creating another import blindly.
An illustrative operation register can contain an operation key, task ID, input checksum, authorized owner and output references. Decide how identical submissions are handled. A genuinely repeated import may be a new operation; a retry caused by a lost connection should usually recover the prior one. Make that distinction in the application contract.
Avoid treating a task ID as a secret that grants access by itself. Authenticate each request and verify that the caller may inspect or update that task. Test a second user with a different scope. They should receive a clear rejection without learning the private task's input or output.
Make requested input durable
An input request should explain which decision blocks progress and how the answer will be used. For a CSV import, “Which column is the supplier identifier?” is better than “Please confirm.” Show the relevant column names and a safe sample so the user can make a grounded choice.
Save the answer before resuming dependent work. If the client closes after responding, the worker should not lose the decision and ask again indefinitely. Bind the answer to the task and the exact input revision. If a different file replaces the original, revisit any mapping decision that depended on its columns.
Also define what happens when the answer is invalid or late. The user needs a visible outcome, such as “the task has expired” or “this column no longer exists in the current file.” A successful input-request response does not prove that the import resumed or completed. Continue observing the same task until it reaches a known state.
Run the reconnect and cancellation checks
Use synthetic records for a small acceptance exercise. Submit one import, retain its task ID and close the client while work is pending. Reconnect and retrieve the same task. Verify that the input reference, progress and final result belong to the original operation.
Next, create an input-required case and restart the client before responding. Check that the question remains available and that the saved answer resumes the intended work. Then submit a duplicate operation request and verify your application's defined recovery behavior.
Finally, request cancellation after a controlled checkpoint. Inspect the terminal state and any saved records. The test should reveal whether the application promises rollback, partial completion or another documented behavior. Choose one real contract and expose it to the user; do not assume that the protocol automatically reverses application-side changes.
Prototype the progress interface with Atoms
Atoms can help you build a task-monitor interface from a precise brief. Start with a simulated state sequence and a clear separation between task status, input requests and output verification. A generated app is not a confirmed MCP Tasks implementation until its protocol connection has been built and tested.
Build a long-running import monitor with synthetic supplier records.
Store operation key, task ID, file reference, owner, status and outputs.
Show working, input_required, completed, failed and cancelled states.
Keep cancel requested distinct from a terminal cancellation result.
Provide a column-mapping input form and persist its answer before resume.
Simulate reconnect, duplicate submission, expired input and partial work.
Require an explicit final result with saved-record and rejected-row links.
Label the protocol connection as simulated until a real server is tested.
List the remaining authentication and persistence work before launch.
The agent orchestration guide offers related workflow context. Use the prototype to decide what a user needs to see, then validate the actual client/server behavior with the extension documentation.
Use the sample brief to start a durable job dashboard in Atoms.
Conclusion
MCP Tasks make long-running work observable across requests, but the application must preserve identity, decisions and side effects. Start with the current extension contract and test reconnects, input, duplicates and cancellation. Build the review interface in Atoms when that helps clarify the experience, while keeping protocol compliance a separate acceptance step.
Create a first version with synthetic data and review the results.
FAQs
Q1: Does a task handle mean the operation succeeded?
No. A handle identifies accepted work that the client can inspect later. The operation may still be running, waiting for input, failed or cancelled. Read the task state and retrieve its final result before claiming success. Then check the result against the tool's promised outcome. For an import, this may require verifying saved records as well as rejected rows. A quick initial response is useful for responsiveness, but it cannot replace completion evidence from the operation the user actually requested.
Q2: What should survive when the client disconnects?
The application should retain enough information to reconnect to the intended operation: its durable task identity, owner, input reference, status and final output or failure. Any answered input request should also remain available to the worker. The current extension documentation describes polling a task after reconnecting; your backend still has to implement the corresponding durable state. Test the same task through a client restart and verify the resulting records. Starting another operation after every disconnect defeats the recovery benefit and can duplicate side effects.
Q3: Does cancellation undo records the task already saved?
Do not assume that it does. Cancellation is cooperative, and the application's own transaction and checkpoint design determines what happens to completed work. Your user interface should show that cancellation was requested, then display the observed final state and any relevant outputs. Define whether the operation rolls back, keeps an accepted partial result or requires a separate recovery action. Test that behavior on synthetic data and document it in the workflow. A cancelled status without an explanation of side effects may leave the user with an incomplete understanding.
