Cursor background agents on a shared backlog

What background agents are now

A Cloud Agent is a Cursor agent in an isolated VM with a full development environment: it clones your repo, sets itself up from .cursor/environment.json (an idempotent install command, a snapshot, or a Dockerfile), works on a separate branch, and pushes to your repo for handoff as a merge-ready PR. You can start one from the editor, the web at cursor.com/agents, the iOS app, Slack, a GitHub or Bitbucket comment, a Linear issue, or the API. Per Cursor’s docs it is available on paid plans, billed at API pricing for the model it runs. The authoritative reference is Cursor’s Cloud Agents documentation.

The search term everyone still uses is background agents, so this guide uses both names; they are the same feature.

Two Cursors, two configs

Here is the trap. The Cursor editor on your machine reads MCP servers from .cursor/mcp.json, and a local stdio command configured there works because it runs where you are. Cloud Agents are wired somewhere else: per Cursor’s docs their MCP servers are added in the dashboard at cursor.com/agents, where both HTTP and stdio transports are supported. And a Cloud Agent works from an isolated VM, not from your machine, so an MCP server that only exists on your laptop is not something it can reach. Give it an endpoint that is reachable from the VM.

So a local proxy setup, the kind the connect page wires for the editor, will work in the editor and silently be absent for a Cloud Agent. Don’t expect an error: the agent just runs without your queue tools. For cloud, configure a remote HTTP MCP server instead.

Wiring the queue into a Cloud Agent

Retasc, the shared queue this guide wires in, speaks the shape Cloud Agents want: its primary surface is a remote MCP server over HTTP. The wiring is two steps.

Step one is the remote-key flow from the docs: it exists for this case, hosted agents that cannot run a local keystore. Step two is Cursor’s dashboard: add the endpoint with an authorization header, and every Cloud Agent your team launches can reach the queue. In the local editor, keep the .cursor/mcp.json config from the connect page; the two configs coexist.

One environment note: Cloud Agents read .cursor/environment.json at the commit they start from, and per Cursor’s docs the update script must be idempotent. Nothing queue-specific goes there; the queue arrives through MCP, not through the repo.

What a run looks like

Cloud Agents are launched per task: something, or someone, starts a run. A queue turns that launch prompt into a standing order: pull work from Retasc and keep pulling until the queue is dry.

Within a run the agent behaves like any queue worker: the queue’s next_issue tool atomically claims the top unblocked issue and returns the server-computed branch name; the claim is a 30-minute lease that renews while the agent works; a checkpoint records progress at milestones. If the VM dies mid-issue, the lease lapses and the issue returns to the pool, checkpoint attached, for any runtime to resume; the mechanics are in the parallel agents guide. An empty pull returns counts of what is ready, blocked and claimed, which is the agent’s signal to stop cleanly.

Recurring dispatch is on you: Cursor’s docs describe no built-in scheduler, so a run starts when you, a teammate, a Slack mention, or an API call starts one. Teams that want a heartbeat cadence point a cron at the API.

Mixing Cursor into the fleet

Nothing about the queue is Cursor-shaped, and that is the point. A Cloud Agent, three Claude Code terminals from the parallel agents setup, and a CI runner can all pull from the same backlog: claims are atomic and serialized per project, so simultaneous pulls get different issues, and every action carries a runtime label, so the dashboard shows which tool did what for whom. A checkpoint a Claude Code agent leaves on Friday is resumable by a Cloud Agent on Monday; the handoff crosses runtimes because the state lives in the queue, not in any tool. That mixed shape has a name and a guide of its own.

Questions that come up

The queue side takes minutes: the remote-key flow is in the onboarding docs, the endpoint is https://mcp.retasc.com/mcp, and signup seeds the first $10 of usage.