What a Cursor Cloud Agent does
A Cursor Cloud Agent clones your repo into an isolated VM with a full development environment, configured through .cursor/environment.json using an idempotent install command, a snapshot, or a Dockerfile. It 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. According to Cursor’s Cloud Agents documentation, the authoritative reference, it is available on paid plans and billed at API pricing for the model it runs.
Background agents is still the search term everyone uses. This guide uses both names for the same feature.
The editor and Cloud Agents use different configs
The Cursor editor reads MCP servers from .cursor/mcp.json, where a configured local stdio command works because it runs on your machine. Cursor’s docs put Cloud Agent MCP configuration in the dashboard at cursor.com/agents, with support for both HTTP and stdio transports. Cloud Agents run in isolated VMs, so they need an endpoint reachable from the VM and cannot reach a server that exists only on your laptop. For your local editor, npx @retasc/cli@latest setup configures every MCP harness it finds, including Cursor, in one pass.
.cursor/mcp.json · stdio runs on your machineA local proxy setup from the wire page works in the editor, but its queue tools are silently absent from a Cloud Agent. You should not expect an error when this happens, because the agent runs without those tools. Configure a remote HTTP MCP server for cloud use.
Connect a Cloud Agent to the queue
Retasc exposes its shared queue primarily through a remote MCP server over HTTP, which gives Cloud Agents an endpoint they can reach. Connecting it takes two steps.
Step 1 is to follow the remote-key flow in the docs, which covers hosted agents that cannot run a local keystore. Step 2 is to add the endpoint with an authorization header in Cursor’s dashboard so every Cloud Agent your team launches can reach the queue. For your local editor, keep the .mcp.json config the wire page writes. The two configurations coexist.
Cloud Agents read .cursor/environment.json from the commit they start from, and Cursor’s docs require the update script to be idempotent. Nothing specific to the queue belongs in that file. Queue access comes through MCP, outside the repo.
A run keeps pulling work
A Cloud Agent starts when someone or something launches it for a task. With a queue, you can make that launch prompt a standing instruction to pull work from Retasc and keep pulling until the queue is dry.
During a run, the agent calls the queue’s next_issue tool to atomically claim the top unblocked issue and receive its server-computed branch name, as described in the parallel agents guide. Each claim has a 30-minute lease, renewed by heartbeats or checkpoints while checkpoints record progress at milestones. If the VM dies mid-issue, the lease lapses and the issue returns to the pool with its checkpoint attached, ready for any runtime to resume. An empty pull returns counts of ready, blocked and claimed issues, which tells the agent to stop cleanly.
Cursor’s docs describe no built-in scheduler, so you need to arrange recurring dispatch. You, a teammate, a Slack mention, or an API call can start a run. Teams that want a heartbeat cadence point a cron at the API.
Cursor can share a queue with other runtimes
A Cloud Agent, three Claude Code terminals from the parallel agents setup, and a CI runner can pull from the same backlog because the queue works across runtimes. Claims are atomic and serialized per project, so simultaneous pulls get different issues, while runtime labels on every action let the dashboard show which tool did what for whom. A checkpoint left by Claude Code on Friday can be resumed by a Cloud Agent on Monday because the state lives in the queue. This mixed fleet has a name and a guide of its own.
Questions about Cursor background agents
Can Cursor background agents (now Cloud Agents) use MCP?
Cursor’s docs say Cloud Agents, the current name for background agents, support MCP servers over HTTP and stdio, with OAuth for servers that need it. The configuration lives in the cursor.com/agents dashboard, which Cursor documents as the place to add MCP servers for a cloud agent. Do not assume the .cursor/mcp.json in your repo carries over. Configure MCP in the dashboard.
Why does a background agent ignore my .cursor/mcp.json?
That file configures the local editor. Cursor documents a separate configuration path for Cloud Agents in the cursor.com/agents dashboard, and those agents run in isolated VMs. A server that exists only on your machine, including a local proxy, cannot be reached from that VM, so give the cloud agent a remote HTTP MCP endpoint.
Can Cursor background agents share a backlog with Claude Code?
A Cloud Agent and a Claude Code session can share the queue because it is a remote MCP server with atomic claims. When they pull at the same moment, they get different issues, and either runtime can resume a checkpoint left by the other. Every action carries a runtime label, so the dashboard shows which tool did what.
Do Cursor background agents open pull requests?
Cursor’s docs describe Cloud Agents working on a separate branch and pushing to your repo for handoff as merge-ready PRs. Use the queue’s server-computed branch name for each issue so both systems agree on where the work lands.
The queue takes minutes to connect using the remote-key flow in the onboarding docs and the endpoint https://mcp.retasc.com/mcp. Signup gives you the first $10 of usage.