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

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