Mastra adds MCP Tasks for background tool calls
Mastra has introduced MCP Tasks, a way to run long-running tool calls in the background through its MCPServer and MCPClient. The feature allows agents to continue responding to users while slow or expensive computations run, then receive the result when the task is complete.
- MCP Tasks run long-running tool calls in the background.
- MCP clients poll servers using a task ID and status.
- Agents can continue responding while tasks are running.
- Tasks can pause for human input with suspend().
- The API is experimental and may change.
From blocked tool calls to background tasks
Before MCP Tasks, MCP tool calls were synchronous. Each call used a single HTTP request that stayed open until the operation finished, blocking the agent loop and preventing the agent from responding to new user requests.
With the new approach, an MCP server can quickly return a task ID. That completes the HTTP request and frees the agent loop, while the MCP client polls the server for updates. The client receives a task status of working, input_required, completed, failed, or cancelled.
Mastra says the design also addresses a limitation of its existing background tasks primitive. A tool call could eventually fail if it outlasted a proxy timeout or a load balancer's idle limit. MCP Tasks separate the initial request from the longer-running work.
Agents can receive results when work finishes
When a task completes, Mastra sends the agent a notification signal. The signal reaches an active run on its next model request, rather than waiting for the agent loop to finish. The example in Mastra's announcement shows an agent answering questions while a 30-day repository report runs as an MCP task, then displaying the finished report as a dashboard.
Tasks can also pause for human input. Tools that run as tasks can use suspend(), putting the task into the input_required state until the client responds. This supports workflows where a person must approve an action before the tool continues.
MCP Tasks build on Mastra's MCP 2.0 support and follow MCP events as an addition to the framework's MCP server and client primitives. The announcement identifies the feature as the MCP Tasks extension, SEP-2663.
Configuration and availability
Mastra says developers can install the latest packages with npm install @mastra/mcp@latest @mastra/core@latest. The feature requires @mastra/[email protected] and @mastra/[email protected] or later, and was added in PR #28420.
Background tasks must be enabled on the Mastra instance. On an MCP server, tools can be configured to run as tasks always, auto, or off. The auto option uses a two-second syncWindowMs by default and switches to a task when a call takes longer. Off is the default.
On the client, developers enable tasks so it can poll the server, and can configure inputRequests for tools that require human input. Mastra says MCP Tasks are still experimental, so the API may change between releases.
Mastra: Introducing MCP Tasks in Mastra | Mastra Blog
