Skip to main content
Glama

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-mcp

3. 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

cursor_launch

Launch an agent + first run. Returns agent_id and run_id. Supports repos, repo-less, model pick, plan/agent mode, idempotency keys.

cursor_status

Poll a run's status. Run status is the source of truth (agent ACTIVE ≠ still running).

cursor_result

Wait for a run to finish and return its result (truncated safely).

cursor_followup

Send a follow-up; starts a new run (returns the new run_id).

cursor_cancel

Cancel the active run (terminal; follow up to continue).

cursor_list

List agents, newest first — your reconciliation tool.

cursor_models

List model ids + params + variants. Call before launching; ids aren't guessable.

cursor_whoami

Verify auth / identity.

cursor_usage

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): direct https://api.cursor.com with CURSOR_API_KEY. Works anywhere.

  • sandbox (experimental): shells out to a cursor-agent CLI on PATH, for sandboxed agent environments that broker the credential for you. Select explicitly with CURSOR_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: run cursor_list and match by creation time, or retry the launch with the same idempotency_key — replays can never duplicate.

  • cursor_followup says "agent is busy" — a run is still active. Poll cursor_status until 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_KEY from 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 tools
cursor_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

    A4/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables delegating coding tasks to Cursor Cloud Agents from Claude Code, Codex, or Grok, with scoped repository access, progress monitoring, follow-ups, and result reporting.
      23
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      7
      MIT