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_reposto detect your repository - Break the project into independent tasks
- Group tasks into phases (parallel → sequential)
- Provide exact prompts for each
create_taskcall
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