cursor-cloud-agents-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cursor-cloud-agents-mcp launch a Cursor agent on my repo to fix the failing tests and show the result"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cursor-cloud-agents-mcp
An MCP server that lets your AI assistant drive Cursor Cloud Agents. Launch agents on your repos (or repo-less for research), pick any Cursor model, follow up mid-run, fetch results, and check spend — from Claude Code, Cursor Desktop, Muse, or any MCP client.
If you've searched for "Cursor Cloud Agents MCP server", "MCP server for Cursor", "connect Claude Code to Cursor", "Cursor API MCP integration", or "launch Cursor agents programmatically" — this is it.
Why this exists
Cursor's Cloud Agents API is powerful but raw: you manage agent/run lifecycles, idempotency, timeouts, and model IDs by hand. The community MCP bridges we found were built on the retired v0 API and left unmaintained. This one is built on the current v1 API (agent + run split), bakes in the hard-won lessons (idempotent launches, generous timeouts, never trust a timeout as failure), and is tested against the live API.
It was designed in the open: the v1 spec was reviewed by four AI models, verified against Cursor's live docs and community reports, and the code was reviewed by two more before release.
Related MCP server: cursor-sdk-mcp
Quickstart
1. Get a Cursor API key. Mint a User API key at Cursor Dashboard → API Keys.
2. Install. (PyPI publishing is on the way — until then, install from git.)
pip install git+https://github.com/TygartMedia/cursor-cloud-agents-mcp
# or try it without installing:
uvx --from git+https://github.com/TygartMedia/cursor-cloud-agents-mcp cursor-cloud-agents-mcp3. Add it to your MCP client. ⚠️ Set the key in the client's env block, not just your shell — MCP servers are spawned with a scrubbed environment and won't inherit shell variables.
Claude Code (~/.claude.json or project .mcp.json):
{
"mcpServers": {
"cursor-cloud-agents": {
"command": "cursor-cloud-agents-mcp",
"env": { "CURSOR_API_KEY": "paste-your-key-here" }
}
}
}Cursor Desktop (MCP settings):
{
"mcpServers": {
"cursor-cloud-agents": {
"command": "uvx",
"args": ["--from", "git+https://github.com/TygartMedia/cursor-cloud-agents-mcp", "cursor-cloud-agents-mcp"],
"env": { "CURSOR_API_KEY": "paste-your-key-here" }
}
}
}4. Smoke test. Ask your assistant: "Use cursor_whoami to verify my Cursor key, then list my models."
Tools
Tool | What it does |
| Launch an agent + first run. Returns |
| Poll a run's status. Run status is the source of truth (agent |
| Wait for a run to finish and return its result (truncated safely). |
| Send a follow-up; starts a new run (returns the new |
| Cancel the active run (terminal; follow up to continue). |
| List agents, newest first — your reconciliation tool. |
| List model ids + params + variants. Call before launching; ids aren't guessable. |
| Verify auth / identity. |
| Token usage and cost per agent or run. |
Launching well
Give the agent a complete prompt: goal, constraints, and how to verify it's done. Vague prompts produce vague agents. Omit repo_url for research/review/writing tasks; pass a GitHub https URL when it should write code. Omit starting_ref to use the repo default — never assume main. Omit model entirely to use your default chain (never send the literal string "Auto" — the API rejects it).
Transports
rest(default): directhttps://api.cursor.comwithCURSOR_API_KEY. Works anywhere.sandbox(experimental): shells out to acursor-agentCLI on PATH, for sandboxed agent environments that broker the credential for you. Select explicitly withCURSOR_TRANSPORT=sandbox— it is never auto-detected. The CLI contract is unproven against public builds; expect rough edges.
Troubleshooting
Launch reported
status: "unknown"— the API may have accepted the launch but the response was slow (launches can take minutes). The agent may have been created: runcursor_listand match by creation time, or retry the launch with the sameidempotency_key— replays can never duplicate.cursor_followupsays "agent is busy" — a run is still active. Pollcursor_statusuntil terminal, then follow up.Auth errors — run
cursor_whoami. Keys are minted at Dashboard → API Keys."I launched an agent but can't see it in Cursor" — API-created agents are hidden from the dashboard's default list; use the Source filter.
Key in logs — the client scrubs
CURSOR_API_KEYfrom every error path, but still: never paste your key into a prompt.
What it costs
Cloud agents spend real Cursor quota. Use cursor_usage to check per-run cost. This server makes no billing decisions for you.
License
MIT.
Available Tools
9 toolscursor_cancelA
Cancel the active run. Cancellation is terminal — to continue the conversation, send a follow-up (which starts a new run on the same agent). Does not archive the agent. Returns the run's actual post-cancel state.
Inputs: run_id (required), agent_id (required).
cursor_followupA
Send a follow-up prompt to an agent. Starts a NEW run — the returned run_id is what you poll with cursor_status (the old run_id is stale).
Only call when the previous run is terminal; a follow-up during an active run fails with "agent is busy" — poll cursor_status first.
Inputs: prompt (required), agent_id (required).
cursor_launchA
Launch a Cursor cloud agent and enqueue its first run.
Pass a complete task prompt: goal, constraints, and how to verify done — vague prompts produce vague agents. Repo-less launches (no repo_url) are for research, reviews, and writing; pass repo_url (a GitHub https URL) when the agent should write code. starting_ref is a branch or SHA; omit it to use the repo default (never assume "main").
Call cursor_models first and pass a model id verbatim — never guess ids, and never pass the literal string "Auto" (omit model instead). model_params is a list of {key, value} dicts for per-model options (only ids/params from cursor_models are accepted). mode is "agent" or "plan".
Returns agent_id AND run_id: poll cursor_status with both. Launch can take minutes; if the tool reports status "unknown", the agent may still have been created — reconcile with cursor_list, or retry with the same idempotency_key (replays are safe and never duplicate).
Inputs: prompt (required), mode, name, model, +4 more.
cursor_listA
List your agents, newest first. Use this to reconcile after a launch reported status "unknown" (match by name/creation time), or to find an agent you lost track of.
Inputs: limit.
cursor_modelsA
List available Cursor models with their ids, parameters, and variants. Call this before cursor_launch and pass the id verbatim — ids are not guessable. Each model may support params (e.g. reasoning effort); only valid id/params combinations from this list will be accepted.
Inputs: no named parameters.
cursor_resultA
Wait for a run to finish (polling server-side) and return its result.
Convenience wrapper over cursor_status for when you just want the final answer. Waits at most timeout_s seconds (clamped to 5 min) — on timeout, keep polling with cursor_status using the returned run_id. Large results are truncated with truncated=true. Transient API blips (429/5xx) are retried with backoff.
Inputs: agent_id (required), run_id, timeout_s.
cursor_statusA
Check a run's status. Run status is the source of truth — the agent's lifecycle status (ACTIVE/IDLE) is NOT "is it still working".
If run_id is omitted, the agent's latest run is used. Poll this every 10-30 seconds; never sleep inside a tool call. When terminal=true, result holds the agent's final reply.
Inputs: agent_id (required), run_id.
cursor_usageB
Token usage and cost for an agent (or one run). Costs real money — check this when a run felt expensive.
Inputs: agent_id (required), run_id.
cursor_whoamiA
Verify your API key works and see which identity it belongs to. Call this first if anything else fails with auth errors.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Tools map to distinct lifecycle actions (launch, poll status, wait for result, follow up, cancel, list, discover models, verify identity, check usage). The only real overlap is cursor_status vs cursor_result, but their descriptions clearly distinguish granular polling from a blocking final-answer wrapper.
All tools share a consistent cursor_ prefix and snake_case formatting, making the set easy to scan. The minor deviation is mixing verb-style names (launch, followup, cancel, list) with noun-style names (status, result, models, usage, whoami), but the convention remains predictable.
Nine tools is well-scoped for managing cloud agents, with each tool earning its place across the launch-monitor-followup-cancel lifecycle plus supporting discovery (models, identity, usage). There are no redundant or filler tools.
The surface covers the core lifecycle: launch, poll status, wait for result, follow up, cancel, and list agents, plus model discovery and usage checks. Missing are explicit agent archival/deletion and a dedicated get-agent-details tool, though these are minor gaps for most workflows.
Maintenance
Related MCP Connectors
AI cloud for agents: launch GPUs, run jobs that stop their own billing, schedule runs.
The cloud for agents. Tools for AI agents to register, build, and deploy other agents. Zero human required.
MCP-first control plane for ProAgentStore agents and private instances.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables programmatic control of Cursor's cloud-based AI agents for automated code generation and repository management via standardized MCP tools.27 npm6MIT
- AlicenseAqualityDmaintenanceEnables MCP clients to invoke Cursor SDK's agent runtime, run coding agents, list models, and continue conversations.41MIT
- AlicenseAqualityBmaintenanceEnables delegating coding tasks to Cursor Cloud Agents from Claude Code, Codex, or Grok, with scoped repository access, progress monitoring, follow-ups, and result reporting.23MIT
- AlicenseAqualityCmaintenanceEnables an orchestrator like Claude Code to hand coding work off to Cursor SDK agents, run as detached background jobs that survive the session and can be listed, inspected, steered, resumed, or stopped. Agents are asynchronous and reusable across follow-up turns, letting expensive frontier models delegate cheaply without blocking or paying to read the results.7MIT