MCP Tasks background jobs definition
MCP Tasks are a Model Context Protocol mechanism for running a tool call as a long-lived background job rather than a single blocking request. The client starts the task, receives a handle immediately, and can then poll its status, cancel it, or come back for the result later.
MCP Tasks let an agent kick off work that takes minutes or hours by turning a tool call into a job it can poll, cancel, or collect later, instead of holding a connection open and timing out. Long content operations fit this shape well: a bulk transform or migration across thousands of Sanity documents can run as a task and land its output as drafts, so an editor reviews the result before anything publishes.
MCP Tasks let a Model Context Protocol server accept a tool call, acknowledge it immediately, and keep working on it in the background while the client continues with other work. The Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources, published by Anthropic and documented at modelcontextprotocol.io.
The practical difference is what comes back first. An ordinary tool call returns the finished result. A task returns a handle, an identifier the client can use to ask "is it done yet?", stop the job, or fetch the output once it finishes. The work continues on the server even if the client is not watching.
That shift matters because agents are increasingly asked to do work that does not fit in a single request. Translating a whole site, re-embedding a dataset, or auditing thousands of records are jobs measured in minutes rather than seconds, and a request-response call is the wrong container for them.
An ordinary MCP tool call is synchronous: the client sends a request, waits with the connection open, and receives the answer in the same exchange. MCP Tasks are asynchronous: the client sends a request, gets back a task handle, and retrieves the result in a separate exchange later.
The consequences show up in four places. First, duration. A synchronous call is bounded by whatever timeout the client, the server, and any proxy in between agree on, while a task is bounded by how long the server is willing to keep working. Second, visibility. A synchronous call is opaque until it returns, while a task can report progress as it runs. Third, control. A synchronous call is usually abandoned, while a task exposes an explicit cancel. Fourth, continuity. A synchronous call dies with the connection, while a task can be resumed by a later session that knows the identifier.
Tasks are not better by default. For a lookup that takes 200 milliseconds, the handle-and-poll cycle is overhead. Tasks earn their complexity only when the work outlives the request.
An agent runs a long job through MCP Tasks in a repeating loop of start, poll, and collect. In a coding agent such as Claude Code, the pattern looks like this.
The agent calls a tool that the server has declared as task-capable, for example a bulk update across a content dataset. The server validates the request, queues the work, and returns a task identifier immediately, typically in well under a second. The agent reports to the user that the job has started, and then it can take other instructions, read files, or answer questions in the meantime.
Periodically, or when the user asks, the agent polls the task identifier for status. The server answers with something like running, with a progress figure if it tracks one, failed with an error, or completed with a result or a pointer to where the result lives. If the user changes their mind, the agent issues a cancel against the same identifier and the server stops the work.
The important property is decoupling: the agent conversation and the job execution are separate. A session can end, a laptop can sleep, and the job continues on the server. When the agent returns with the identifier, the result is waiting.
MCP Tasks suit jobs where the unit of work is a whole collection rather than a single item. Four patterns come up repeatedly in content and data work.
Bulk content updates: rewriting a product description field across an entire catalog, applying a new tone of voice, or normalizing a data shape after a schema change. Whole-site translation: generating localized versions of every page in a site, where the per-document cost is small but the document count is large. Re-embedding a dataset: regenerating the vector representations that power semantic search or retrieval-augmented generation after a model change or a content overhaul. Auditing at scale: checking thousands of documents for broken links, missing alt text, accessibility problems, or compliance issues, and reporting the exceptions.
What these share is long runtime, progress worth reporting, and a result the user should inspect rather than accept blindly. All three argue for a task, not a blocking call.
Content operations fit task-style execution because the expensive step is not the write, but the work that precedes it. Generating a translation, rewriting a field with a language model, or computing an embedding takes real time per document, and the cost multiplies with the dataset size.
Sanity is the AI Content Operating System, the intelligent back end for companies building AI content operations at scale, and the primitives that make long jobs safe there are the same ones that make everyday editing safe. Bulk transformations run through the Agent API against structured documents rather than rendered pages, so a job changes a named field across many documents rather than pattern-matching through markup. Migrations run over the same structured content. Output can land as drafts, which keeps machine-written changes in a reviewable state until a human decides they are ready.
That last point is what makes background execution tolerable in a production content system. A long job that publishes directly is a risk measured by the number of documents it touched. A long job that produces drafts is a queue of proposals, and the review step is where editorial judgment returns.
The main risks with MCP Tasks are idempotency, partial failure, and runaway cost, and all three come from the same source: the job keeps running when nobody is watching it.
Idempotency matters because a client that loses a connection may retry a start request, and a server that treats the retry as a new job will do the work twice. Giving each task a client-supplied key, so a repeat request returns the existing task rather than creating a second one, is a common fix.
Partial failure matters because a job over ten thousand documents will not fail cleanly at the start. It will fail at document 6,412, which raises the question of what happened to the first 6,411. A task result that reports counts of succeeded, skipped, and failed items, with the failures itemized, is more useful than a single error string.
Runaway cost matters because an agent can start a job it is not watching, and it can start an expensive one. Cancellation needs to stop the work, not just the reporting, and a spend or item-count ceiling is worth setting before the first run, not after the first surprise.
Explore Sanity Today
Understanding MCP Tasks background jobs is just the beginning. Take the next step and discover how Sanity can enhance your content management and delivery.
Last updated: