@mciver87/cloud-agent-wrapper

CLI + MCP server for launching, resuming, and managing Cursor Cloud Agents from any terminal or MCP-capable agent.

Backed by @cursor/sdk. One shared core, two front-ends:

• CLI (cloud-agent new|list|get|resume|cancel) — for humans, shell scripts, CI, or any agent that can shell out.

• MCP server (cloud-agent-mcp) — exposes the same operations as native tools to Cursor Desktop, cursor-agent CLI, Claude Desktop, Codex, and any other MCP-capable client.

Install

npm install -g @mciver87/cloud-agent-wrapper
export CURSOR_API_KEY="crsr_..."   # from https://cursor.com/t/<team>/api

Related MCP server: cursor-sdk-mcp

CLI usage

# Launch — auto-detects repo from `git remote get-url origin`
cloud-agent new "fix the lint failures and open a PR"

# Explicit repo + model + auto-PR
cloud-agent new --repo foo/bar --model opus-5.5 --pr "rebase onto main"

# List recent cloud agents
cloud-agent list
cloud-agent list --json --limit 50

# Fetch metadata
cloud-agent get bc-abc123

# Follow-up on an existing agent
cloud-agent resume bc-abc123 "also update the changelog"

# Cancel a running agent
cloud-agent cancel bc-abc123

Exit codes

• 0 — run finished successfully

• 1 — startup / config / auth failure (couldn't even begin)

• 2 — run executed but completed with an error status

JSON mode

Add --json to any command for machine-readable output. For new and resume, each line of stdout is one SDKMessage JSON object; for list/get/cancel, a single JSON object.

MCP server usage

Register in your client's mcp.json. Example for Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "cloud-agent": {
      "command": "cloud-agent-mcp",
      "env": {
        "CURSOR_API_KEY": "crsr_..."
      }
    }
  }
}

After restarting the client, these tools become callable natively:

Clients that respect inputSchema get full argument validation (Zod schemas). Clients that don't still see rich descriptions in the tool list.

Model shorthands

Any of these --model values map to full IDs:

Pass any other string through verbatim. If omitted, your team's default model is used.

Repo resolution

If --repo is omitted, cloud-agent runs git remote get-url origin in the current directory and parses owner/name from the URL (both git@github.com:owner/name and https://github.com/owner/name[.git] forms work). Pass --repo owner/name or --repo https://github.com/owner/name to override.

API key

Required: CURSOR_API_KEY env var. Generate at cursor.com/t/<team>/api. For long-term use, add to ~/.zshenv (chmod 600) so every shell + subprocess inherits it.

Service-account keys work the same way; the Cursor backend decides whether PRs open as the key owner or the Cursor GitHub App.

Development

git clone https://github.com/mciver87/cloud-agent-wrapper
cd cloud-agent-wrapper
npm install
npm run build
npm run typecheck

Source layout:

• src/core.ts — SDK wrapper (launch/list/get/resume/cancel). All SDK knowledge lives here.

• src/cli.ts — commander-based CLI, exits with 0/1/2 per the SDK skill convention.

• src/mcp.ts — MCP server, same operations as native tools.

• bin/cloud-agent.mjs + bin/cloud-agent-mcp.mjs — ESM shebang shims.

License

MIT