Cloud Agent MCP Server

MCP server for the Cursor Cloud Agents API. Lets AI assistants create and manage cloud agents that work on GitHub repositories.

Quick Start

# Install
npm install -g cursor-cloud-agent-mcp

# Set your API key
export CURSOR_API_KEY=your_api_key_here

# Use with Cursor (create .cursor/mcp.json)
{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npx",
      "args": ["-y", "cursor-cloud-agent-mcp"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

Installation

Install from npm

npm install -g cursor-cloud-agent-mcp

Or install locally in your project:

npm install cursor-cloud-agent-mcp

Install from Source

If you're developing or want to run from source:

# Clone and install dependencies
git clone https://github.com/jxnl/cursor-cloud-agent-mcp
cd cloud-agent-mcp
npm install

# Set your API key
export CURSOR_API_KEY=your_api_key_here

# Run HTTP server
npm start
# Server runs at http://localhost:3000/mcp

# Or run stdio server
npm run start:stdio

Configuration

Environment Variables

Variable	Required	Description
`CURSOR_API_KEY`	Yes	API key from cursor.com/settings
`PORT`	No	Server port for HTTP version only (default: 3000)

Connecting Clients

Cursor

Option 1: Using npm package (Recommended)

After installing via npm, create .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npx",
      "args": ["-y", "cursor-cloud-agent-mcp"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "cursor-cloud-agent-mcp",
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

Option 2: From source (Development)

If running from source, create .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npm",
      "args": ["run", "start:stdio"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

Option 3: HTTP Server (Alternative)

If you prefer the HTTP version, configure it as:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "url": "http://localhost:3000/mcp",
      "headers": {}
    }
  }
}

Then run npm start in a separate terminal to start the HTTP server.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cloud-agent": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector
# Connect to http://localhost:3000/mcp

Usage

Typical Workflow

1. get_repos          → Get current repo URL and branch
2. create_task       → Launch task with prompt
3. get_task          → Check status (CREATING → RUNNING → FINISHED)
4. add_followup       → (optional) Send more instructions while running
5. get_conversation   → Review what the task did

Available Tools

Discovery Tools

Tool	Description
`get_repos`	Detects current git repo (repository URL, branch, uncommitted changes). Optionally lists all accessible repos. Call this first. Note: When using `include_all: true`, filters (`regex_patterns`) are REQUIRED. Fetching all repos has strict rate limits (1/min, 30/hour).
`get_me`	Get API key info (verify authentication)
`get_models`	List available LLM models

Task Lifecycle Tools

Tool	Description
`create_task`	Launch a cloud task with a task prompt
`list_tasks`	List all your cloud tasks
`get_task`	Get status of a specific task
`add_followup`	Send additional instructions to a running task
`get_conversation`	Get full conversation history
`delete_task`	Permanently delete a task

Common Examples

Create a Task

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add a README.md file with installation instructions",
    "repository": "https://github.com/your-org/your-repo",
    "auto_pr": true
  }
}

List Tasks

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED|RUNNING",
    "limit": 10
  }
}

Get Repository Info

{
  "tool": "get_repos"
}

Reference

Tool Documentation

`get_repos` - Get Repositories

Basic usage (current repo only):

{
  "tool": "get_repos"
}

Fetch all accessible repositories (filters REQUIRED):

Important: When using include_all: true, you MUST provide regex_patterns to filter the results. This prevents returning too many repositories.

Filter repositories with regex patterns:

{
  "tool": "get_repos",
  "arguments": {
    "include_all": true,
    "regex_patterns": ["^my-.*"]
  }
}

Multiple filter patterns (OR logic):

{
  "tool": "get_repos",
  "arguments": {
    "include_all": true,
    "regex_patterns": [".*api.*", ".*backend.*", ".*frontend.*"]
  }
}

Specify working directory:

{
  "tool": "get_repos",
  "arguments": {
    "working_directory": "/path/to/project"
  }
}

Filter Examples:

["^my-.*"] - Repos starting with "my-"
[".*api.*"] - Repos containing "api"
["github.com/myorg"] - Repos from specific org
[".*backend.*", ".*server.*"] - Repos matching either pattern

`get_me` - Verify Authentication

{
  "tool": "get_me"
}

`get_models` - List Available Models

{
  "tool": "get_models"
}

`create_task` - Launch a Cloud Task

Basic usage:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add a README.md file with installation instructions",
    "repository": "https://github.com/your-org/your-repo"
  }
}

With branch specification:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Fix authentication bug",
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  }
}

Auto-create PR:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add user authentication",
    "repository": "https://github.com/your-org/your-repo",
    "auto_pr": true
  }
}

Custom branch name:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Implement new feature",
    "repository": "https://github.com/your-org/your-repo",
    "branch_name": "feature/new-feature"
  }
}

Specify model:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Refactor codebase",
    "repository": "https://github.com/your-org/your-repo",
    "model": "claude-4-sonnet-thinking"
  }
}

With plan file:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Implement the features described in the plan",
    "repository": "https://github.com/your-org/your-repo",
    "plan_file": "./plan.md"
  }
}

Complete example with all options:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add comprehensive test coverage",
    "repository": "https://github.com/your-org/your-repo",
    "ref": "develop",
    "branch_name": "feature/add-tests",
    "auto_pr": true,
    "model": "o3",
    "plan_file": "./test-plan.md"
  }
}

`list_tasks` - List All Tasks

Basic listing:

{
  "tool": "list_tasks"
}

Limit results:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 10
  }
}

Pagination with cursor:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 20,
    "cursor": "bc_ghi789"
  }
}

Filter by status:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED|RUNNING"
  }
}

Filter by repository:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": ".*my-repo.*"
  }
}

Filter by branch name:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "feature/.*"
  }
}

Filter by summary content:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": ".*README.*"
  }
}

Combine filters:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED.*my-repo"
  }
}

Filter Examples:

"FINISHED" - Only finished tasks
"RUNNING|CREATING" - Active tasks
".*api.*" - Tasks working on API repos
"feature/.*" - Tasks on feature branches
"FINISHED.*README" - Finished tasks with README in summary
"FAILED|CANCELLED" - Failed or cancelled tasks

`get_task` - Get Task Status

{
  "tool": "get_task",
  "arguments": {
    "id": "bc_abc123"
  }
}

`add_followup` - Send Follow-up Instructions

{
  "tool": "add_followup",
  "arguments": {
    "id": "bc_abc123",
    "prompt": "Also add a troubleshooting section"
  }
}

`get_conversation` - Get Conversation History

{
  "tool": "get_conversation",
  "arguments": {
    "id": "bc_abc123"
  }
}

`delete_task` - Delete a Task

{
  "tool": "delete_task",
  "arguments": {
    "id": "bc_abc123"
  }
}

Response Shapes

All tools return structured JSON responses matching the Cloud Agents API specification. See docs.md for complete API documentation.

`get_me` Response

{
  "apiKeyName": "Production API Key",
  "createdAt": "2024-01-15T10:30:00Z",
  "userEmail": "developer@example.com"
}

`get_models` Response

{
  "models": [
    "claude-4-sonnet-thinking",
    "o3",
    "claude-4-opus-thinking"
  ]
}

`get_repos` Response

{
  "current": {
    "repository": "https://github.com/your-org/your-repo",
    "branch": "main",
    "has_uncommitted_changes": false
  },
  "available": [
    {
      "owner": "your-org",
      "name": "your-repo",
      "repository": "https://github.com/your-org/your-repo"
    }
  ],
  "total_count": 1
}

`create_task` Response

{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "CREATING",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "feature/add-readme",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "autoCreatePr": true,
    "openAsCursorGithubApp": false,
    "skipReviewerRequest": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

`list_tasks` Response

{
  "tasks": [
    {
      "id": "bc_abc123",
      "name": "Add README Documentation",
      "status": "FINISHED",
      "source": {
        "repository": "https://github.com/your-org/your-repo",
        "ref": "main"
      },
      "target": {
        "branchName": "cursor/add-readme-1234",
        "url": "https://cursor.com/agents?id=bc_abc123",
        "prUrl": "https://github.com/your-org/your-repo/pull/1234",
        "autoCreatePr": false,
        "openAsCursorGithubApp": false,
        "skipReviewerRequest": false
      },
      "summary": "Added README.md with installation instructions and usage examples",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "bc_ghi789"
}

`get_task` Response

{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "FINISHED",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "cursor/add-readme-1234",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "prUrl": "https://github.com/your-org/your-repo/pull/1234",
    "autoCreatePr": false,
    "openAsCursorGithubApp": false,
    "skipReviewerRequest": false
  },
  "summary": "Added README.md with installation instructions and usage examples",
  "createdAt": "2024-01-15T10:30:00Z"
}

Status Values: CREATING, RUNNING, FINISHED, FAILED, CANCELLED

`get_conversation` Response

{
  "id": "bc_abc123",
  "messages": [
    {
      "id": "msg_001",
      "type": "user_message",
      "text": "Add a README.md file with installation instructions"
    },
    {
      "id": "msg_002",
      "type": "assistant_message",
      "text": "I'll help you create a comprehensive README.md file..."
    }
  ]
}

`add_followup` Response

{
  "id": "bc_abc123"
}

`delete_task` Response

{
  "id": "bc_abc123"
}

Advanced

Plan Parallel Tasks

Use /plan-parallel-tasks to break down a project for multiple parallel tasks:

/plan-parallel-tasks
project_description: "Add user authentication with login, signup, and password reset"

This will:

Call get_repos to detect your repository
Break the project into independent tasks
Group tasks into phases (parallel → sequential)
Provide exact prompts for each create_task call

Parallelization Rules

CAN run in parallel:

Tasks that modify completely different files
Tasks that create new files without touching shared files

CANNOT run in parallel:

Tasks that modify the same file
Tasks where one depends on another's output
Tasks that both modify package.json, tsconfig.json, etc.

Server Versions

This package includes two server versions:

HTTP Server (src/server.ts): Runs an Express HTTP server on port 3000. Use for remote connections or when you need HTTP endpoints.
Stdio Server (src/server-stdio.ts): Uses standard input/output. Recommended for local integrations. Better for process-based spawning.

Run with:

HTTP: npm start (default)
Stdio: npm run start:stdio

Development

Health Check

The server exposes a health check endpoint:

curl http://localhost:3000/health

Returns: {"status":"ok","service":"cursor-cloud-agent-mcp","version":"1.0.2"}

Publishing to npm

To publish this package to npm:

# Make sure you're logged in
npm login

# Publish
npm publish

The package will be available as cursor-cloud-agent-mcp on npm.

License

MIT

Name		Name	Last commit message	Last commit date
.cursor		.cursor
bin		bin
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Cloud Agent MCP Server

Quick Start

Installation

Install from npm

Install from Source

Configuration

Environment Variables

Connecting Clients

Cursor

Claude Desktop

MCP Inspector

Usage

Typical Workflow

Available Tools

Discovery Tools

Task Lifecycle Tools

Common Examples

Create a Task

List Tasks

Get Repository Info

Reference

Tool Documentation

get_repos - Get Repositories

get_me - Verify Authentication

get_models - List Available Models

create_task - Launch a Cloud Task

list_tasks - List All Tasks

get_task - Get Task Status

add_followup - Send Follow-up Instructions

get_conversation - Get Conversation History

delete_task - Delete a Task

Response Shapes

get_me Response

get_models Response

get_repos Response

create_task Response

list_tasks Response

get_task Response

get_conversation Response

add_followup Response

delete_task Response