Cursor Agents
Arcade.dev tools for operating Cursor Cloud Agents
0.1.0Arcade toolkit for operating Cursor Cloud Agents — AI-powered coding agents that run on repositories in the cloud. This toolkit enables full programmatic lifecycle management of agents and their runs via the Cursor Cloud Agents API.
Capabilities
- Agent lifecycle: Launch agents on GitHub repositories or named environments, retrieve config and status, list all agents, archive/unarchive (reversible), and permanently delete agents.
- Run management: List runs, get real-time status and terminal results (branches, PRs, result text), cancel active runs, and send follow-up prompts to chain multi-turn interactions — including handling
[agent_busy]polling patterns. - Artifacts: List files a cloud agent explicitly uploaded via Cursor's background composer, and obtain time-limited download URLs for individual artifact files.
- Discovery & introspection: List all LLM models available for launch (Claude, GPT, Gemini families), list all reachable GitHub repositories, query per-agent token usage broken down by run, and confirm the authenticated Cursor account identity.
Secrets
CURSOR_AGENTS_API_KEY — A Cursor API key that authenticates all requests to the Cursor Cloud Agents API. Obtain it from your Cursor account dashboard under API keys/settings. The key must have permission to manage cloud agents; verify the correct account is in scope by calling CursorAgents.WhoAmI at the start of a session before launching or modifying agents.
See the Arcade secrets docs for how to store and reference secrets in tools: https://docs.arcade.dev/en/guides/create-tools/tool-basics/create-tool-secrets — you can also manage secrets directly at https://api.arcade.dev/dashboard/auth/secrets.
Available tools(16)
| Tool name | Description | Secrets | |
|---|---|---|---|
Archive a cloud agent so it stops accepting new runs (reversible).
The archive is committed once accepted; if the follow-up read of the agent
fails, the result carries only the agent id with an empty status, and a
get_agent call returns the refreshed state. | 1 | ||
Cancel an active run; cancelling an already-terminal run returns an error.
Cancellation is accepted asynchronously: the returned status reflects the run's
state at the moment of the call and may still be non-terminal even though the
cancel was accepted. Poll the run afterward to confirm it settles to CANCELLED;
do not treat a non-terminal status here as a failed cancel. If the post-cancel
read of the run fails, the result carries an empty status instead of an error.
Upstream failures carry a stable bracketed code before the message when Cursor
supplies one (an open set; the most common here is ``[run_not_cancellable]``,
returned when the run is already terminal). | 1 | ||
Permanently delete a cloud agent. This cannot be undone. | 1 | ||
Get a time-limited download link for one uploaded artifact file.
Artifacts are Cursor "background composer" uploads, not an agent's code changes;
for code output read the run's branch and PR instead. | 1 | ||
Get a cloud agent's configuration and latest run pointer. | 1 | ||
Get token usage for an agent, summed and broken down per run. | 1 | ||
Get a run's current status, and its result, branches, and PR once terminal. | 1 | ||
Launch a Cursor cloud agent on a repository or named environment.
This single call starts the agent and its first run; follow it to completion
with the run tools. | 1 | ||
List your cloud agents, newest first. | 1 | ||
List the artifact files a cloud agent explicitly uploaded.
Artifacts are Cursor "background composer" uploads. Code an agent writes to a repo
lands on the run's branch and PR (see the run's ``branches``), not here, so this is
empty for typical fix-a-repo / open-a-PR tasks. | 1 | ||
List the LLM models available to launch a cloud agent with.
Returns the model ids (e.g. Claude, GPT, and Gemini family models) accepted
by the launch tool's model parameter, with display names and aliases. | 1 | ||
List every GitHub repository Cursor can reach, as repository urls.
The upstream returns the full set in one response, so this is always the
complete list and never a partial page. | 1 | ||
List an agent's runs, newest first.
Listing omits each run's final result text; read an individual run to get it. | 1 | ||
Send a follow-up prompt to an existing agent, starting a new run.
An agent runs one turn at a time. Upstream failures carry a stable bracketed
code before the message when Cursor supplies one (an open set; the most
common here is ``[agent_busy]``). If this returns ``[agent_busy]``, the agent
already has an active run: poll get_run until is_terminal, then resend the
follow-up. | 1 | ||
Restore an archived cloud agent to active.
The restore is committed once accepted; if the follow-up read of the agent
fails, the result carries only the agent id with an empty status, and a
get_agent call returns the refreshed state. | 1 | ||
Return the Cursor account the API key authenticates as.
Call this first in a session to confirm which account you are acting on
before launching or managing any cloud agents. | 1 |
Selected tools
No tools selected.
Click "Show all tools" to add tools.
Requirements
Select tools to see requirements
CursorAgents.ArchiveAgent
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Archive a cloud agent so it stops accepting new runs (reversible). The archive is committed once accepted; if the follow-up read of the agent fails, the result carries only the agent id with an empty status, and a get_agent call returns the refreshed state.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
Requirements
Output
json— No description provided.CursorAgents.CancelRun
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Cancel an active run; cancelling an already-terminal run returns an error. Cancellation is accepted asynchronously: the returned status reflects the run's state at the moment of the call and may still be non-terminal even though the cancel was accepted. Poll the run afterward to confirm it settles to CANCELLED; do not treat a non-terminal status here as a failed cancel. If the post-cancel read of the run fails, the result carries an empty status instead of an error. Upstream failures carry a stable bracketed code before the message when Cursor supplies one (an open set; the most common here is ``[run_not_cancellable]``, returned when the run is already terminal).
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
run_id | string | Required | The active run identifier to cancel. |
Requirements
Output
json— No description provided.CursorAgents.DeleteAgent
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Permanently delete a cloud agent. This cannot be undone.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
Requirements
Output
json— No description provided.CursorAgents.DownloadArtifact
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Get a time-limited download link for one uploaded artifact file. Artifacts are Cursor "background composer" uploads, not an agent's code changes; for code output read the run's branch and PR instead.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
path | string | Required | The artifact's path, as returned when listing artifacts. |
Requirements
Output
json— No description provided.CursorAgents.GetAgent
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Get a cloud agent's configuration and latest run pointer.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
Requirements
Output
json— No description provided.CursorAgents.GetAgentUsage
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Get token usage for an agent, summed and broken down per run.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
run_id | string | Optional | Scope usage to a single run. Leave empty to total across all of the agent's runs. |
Requirements
Output
json— No description provided.CursorAgents.GetRun
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Get a run's current status, and its result, branches, and PR once terminal.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
run_id | string | Required | The run identifier to read. |
Requirements
Output
json— No description provided.CursorAgents.LaunchAgent
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Launch a Cursor cloud agent on a repository or named environment. This single call starts the agent and its first run; follow it to completion with the run tools.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
prompt | string | Required | The coding task for the agent, in natural language. |
repository_url | string | Optional | GitHub repository the agent works on (https://github.com/org/repo; the schemeless github.com/org/repo form returned by list_repositories is also accepted). Leave empty when launching into a named environment, which already pins its repository. |
starting_ref | string | Optional | Branch, tag, or commit to start from. Only valid with a repository url; a named environment pins its own repository and ref. Leave empty to use the repository default branch. |
environment | string | Optional | Named cloud environment to run in. Leave empty to run on the given repository. Cannot be combined with a repository url. |
model | string | Optional | Model id to use. Leave empty to use the account default model. |
mcp_servers | array<json> | Optional | MCP servers to pre-wire into the agent. Leave empty for none. Each item is an object with fields: name (str, required); type (str: "http", "sse", or "stdio"); url (str, for http/sse servers); headers (object of str to str, optional, for http/sse servers); command (str, for stdio servers, run inside the agent VM); args (list of str, optional, for stdio servers); env (object of str to str, optional, for stdio servers). |
env_vars | json | Optional | Environment variables injected into the agent shell, as name/value pairs. At most 50 entries; names cannot start with CURSOR_. Leave empty for none. |
mode | string | Optional | Whether the agent edits code or only produces a plan. Defaults to AGENT.agentplan |
auto_create_pr | boolean | Optional | Open a pull request with the agent's changes when it finishes. Defaults to false. |
work_on_current_branch | boolean | Optional | Commit to the starting branch instead of a new branch. Defaults to false. |
name | string | Optional | Display name for the agent (max 100 characters). Leave empty to auto-name it. |
Requirements
Output
json— No description provided.CursorAgents.ListAgents
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
List your cloud agents, newest first.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
include_archived | boolean | Optional | Include archived agents in the results. Defaults to true. |
pr_url | string | Optional | Only return agents associated with this pull request url. Leave empty for no filter. |
limit | integer | Optional | Maximum agents to return (1-100; values outside the range are clamped). Defaults to 20. |
cursor | string | Optional | Pagination cursor from a previous call. Leave empty for the first page. |
Requirements
Output
json— No description provided.CursorAgents.ListArtifacts
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
List the artifact files a cloud agent explicitly uploaded. Artifacts are Cursor "background composer" uploads. Code an agent writes to a repo lands on the run's branch and PR (see the run's ``branches``), not here, so this is empty for typical fix-a-repo / open-a-PR tasks.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
Requirements
Output
json— No description provided.CursorAgents.ListModels
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
List the LLM models available to launch a cloud agent with. Returns the model ids (e.g. Claude, GPT, and Gemini family models) accepted by the launch tool's model parameter, with display names and aliases.
Parameters
No parameters required.
Requirements
Output
json— No description provided.CursorAgents.ListRepositories
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
List every GitHub repository Cursor can reach, as repository urls. The upstream returns the full set in one response, so this is always the complete list and never a partial page.
Parameters
No parameters required.
Requirements
Output
json— No description provided.CursorAgents.ListRuns
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
List an agent's runs, newest first. Listing omits each run's final result text; read an individual run to get it.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
limit | integer | Optional | Maximum runs to return (1-100; values outside the range are clamped). Defaults to 20. |
cursor | string | Optional | Pagination cursor from a previous call. Leave empty for the first page. |
Requirements
Output
json— No description provided.CursorAgents.SendFollowupRun
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Send a follow-up prompt to an existing agent, starting a new run. An agent runs one turn at a time. Upstream failures carry a stable bracketed code before the message when Cursor supplies one (an open set; the most common here is ``[agent_busy]``). If this returns ``[agent_busy]``, the agent already has an active run: poll get_run until is_terminal, then resend the follow-up.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>) to steer. |
prompt | string | Required | Follow-up instructions for the agent, in natural language. |
mcp_servers | array<json> | Optional | MCP servers scoped to this run only. Leave empty for none. Each item is an object with fields: name (str, required); type (str: "http", "sse", or "stdio"); url (str, for http/sse servers); headers (object of str to str, optional, for http/sse servers); command (str, for stdio servers, run inside the agent VM); args (list of str, optional, for stdio servers); env (object of str to str, optional, for stdio servers). |
mode | string | Optional | Whether the agent edits code or only produces a plan. Defaults to AGENT.agentplan |
Requirements
Output
json— No description provided.CursorAgents.UnarchiveAgent
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Restore an archived cloud agent to active. The restore is committed once accepted; if the follow-up read of the agent fails, the result carries only the agent id with an empty status, and a get_agent call returns the refreshed state.
Parameters
| Parameter | Type | Req. | Description |
|---|---|---|---|
agent_id | string | Required | The agent identifier (bc-<uuid>). |
Requirements
Output
json— No description provided.CursorAgents.WhoAmI
Execution hints
Signals for MCP clients and agents about how this tool behaves.
Reads data without modifying any state in the target system.
May permanently delete or overwrite data in the target system.
Repeated calls with the same inputs produce no additional effect.
Communicates with external APIs, databases, or other services.
Return the Cursor account the API key authenticates as. Call this first in a session to confirm which account you are acting on before launching or managing any cloud agents.
Parameters
No parameters required.
Requirements
Output
json— No description provided.