Cursor Background Agents MCP Server

A clean, modular, and extensible Model Context Protocol (MCP) server that provides access to the Cursor Background Agents API. Built with TypeScript following SOLID principles and clean architecture patterns.

Overview

This MCP server enables AI applications to interact with Cursor's Background Agents API, allowing them to:

• Launch autonomous coding agents on GitHub repositories
• Monitor agent status and progress
• Add follow-up instructions to running agents
• Retrieve agent conversation history
• List available AI models for agents

Features

• ✅ MCP Compliant: Fully implements the MCP specification
• ✅ Clean Architecture: Modular design with clear separation of concerns
• ✅ Type Safe: Written in TypeScript with comprehensive type definitions
• ✅ Input Validation: JSON Schema validation using AJV
• ✅ Error Handling: MCP-compliant structured error responses
• ✅ Comprehensive Tests: 54+ unit tests with high coverage
• ✅ Well Documented: Clear documentation and examples

Architecture

src/
├── domain/          # Core business logic and types
├── application/     # Use cases and service interfaces
├── infrastructure/  # External API clients and adapters
└── presentation/    # HTTP endpoints and controllers

The server follows clean architecture principles with clear dependency inversion:

• Domain: Pure business logic, no external dependencies
• Application: Orchestrates domain logic and defines interfaces
• Infrastructure: Implements external integrations (Cursor API)
• Presentation: Handles HTTP requests and responses

Installation & Usage

Option 1: Use with VS Code / Kilo Code Extension (Recommended)

1. Get your Cursor API key from Cursor Dashboard → Integrations

2. Add to your MCP settings in VS Code:

   • Open VS Code
   • Go to the Kilo Code extension settings
   • Add this configuration to your mcp_settings.json:

{
  "cursor-background-agents": {
    "command": "npx",
    "args": [
      "-y",
      "cursor-background-agent-mcp-server"
    ],
    "env": {
      "CURSOR_API_KEY": "your-actual-cursor-api-key-here"
    },
    "disabled": false,
    "autoApprove": [
      "launchAgent",
      "listAgents",
      "listModels"
    ],
    "alwaysAllow": [
      "getAgentStatus",
      "getAgentConversation",
      "listAgents",
      "listModels",
      "listRepositories"
    ]
  }
}

3. Start using the tools in your Kilo Code chat! The server will automatically start when needed.

Option 2: Manual Installation

For development or standalone usage:

1. Clone the repository:

git clone <repository-url>
cd cursor-background-agent-mcp

2. Install dependencies:

npm install

3. Set environment variables:

export CURSOR_API_KEY="your-cursor-api-key"

4. Build the project:

npm run build

5. Run as MCP STDIO server:

npm run mcp

Or run as HTTP server:

npm start

Usage

Using with VS Code

Once configured in your mcp_settings.json, you can use these tools directly in Kilo Code:

@kilo launch a new Cursor agent to add TypeScript types to my React components

@kilo check the status of my running Cursor agents

@kilo list all available AI models for Cursor agents

MCP Protocol Details

The server implements the Model Context Protocol via STDIO for VS Code integration, and also exposes HTTP endpoints for direct API access:

STDIO Mode (for MCP clients like VS Code)

• Tools: launchAgent, listAgents, listModels, addFollowup, getAgentConversation, getAgentStatus
• Resources: None currently (extensible)
• Transport: JSON-RPC over STDIO

HTTP Mode (for direct API access)

• GET /manifest - Get available tools and schemas
• POST /tool-invoke - Invoke a tool
• POST /resource - Access a resource

Available Tools

launchAgent

Start a new background agent to work on a repository.

Input:

{
  "prompt": {
    "text": "string",
    "images": [
      {
        "data": "base64-string",
        "dimension": { "width": 1024, "height": 768 }
      }
    ]
  },
  "source": {
    "repository": "https://github.com/org/repo",
    "ref": "main"
  }
}

Output:

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

listAgents

Retrieve all background agents for the authenticated user.

Input: {} (empty object)

Output:

{
  "agents": [
    {
      "id": "bc_abc123",
      "name": "Add README Documentation",
      "status": "RUNNING",
      "summary": "Added README.md with installation instructions",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "bc_def456"
}

listModels

Get available AI models for background agents.

Input: {} (empty object)

Output:

{
  "models": [
    { "name": "gpt-4", "recommended": true },
    { "name": "gpt-3.5", "recommended": false }
  ]
}

addFollowup

Send additional instructions to a running agent.

Input:

{
  "agentId": "bc_abc123",
  "prompt": {
    "text": "Also add a section about troubleshooting"
  }
}

getAgentConversation

Retrieve conversation history of an agent.

Input:

{
  "agentId": "bc_abc123"
}

getAgentStatus

Get current status and results of an agent.

Input:

{
  "agentId": "bc_abc123"
}

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Project Structure

src/
├── domain/
│   ├── index.ts           # Domain types and interfaces
│   ├── manifest.ts        # Tool/resource definitions
│   └── errors.ts          # MCP error handling
├── application/
│   ├── index.ts           # Application interfaces
│   └── toolExecutionService.ts # Tool execution logic
├── infrastructure/
│   ├── index.ts           # Infrastructure interfaces
│   └── cursorApiClient.ts # Cursor API HTTP client
├── presentation/
│   ├── manifestController.ts        # GET /manifest
│   ├── toolInvocationController.ts  # POST /tool-invoke
│   └── resourceAccessController.ts  # POST /resource
└── server.ts              # Main server setup

Adding New Tools

1. Define the tool schema in src/domain/manifest.ts:

{
  name: "newTool",
  description: "Description of the new tool",
  inputSchema: { /* JSON Schema */ },
  outputSchema: { /* JSON Schema */ }
}

2. Implement the tool logic in src/application/toolExecutionService.ts:

case "newTool":
  return this.handleNewTool(input);

3. Add corresponding API method in src/infrastructure/cursorApiClient.ts if needed.

4. Write tests in src/__tests__/ following existing patterns.

Error Handling

The server implements MCP-compliant error handling with structured error responses:

{
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'invalidTool' not found",
    "details": { /* optional additional context */ }
  }
}

Error codes include:

• TOOL_NOT_FOUND / RESOURCE_NOT_FOUND
• INVALID_INPUT / INVALID_OUTPUT
• SERVICE_UNAVAILABLE
• AUTHENTICATION_FAILED
• RATE_LIMITED
• TIMEOUT
• INTERNAL_ERROR

Configuration

Environment variables:

Variable	Description	Default
CURSOR_API_KEY	Your Cursor API key (required)	-
PORT	Server port	3000

API Reference

For detailed API documentation, see the Cursor Background Agents API docs.

Publishing

This package is published to npm via automated GitHub Actions workflows. For detailed publishing instructions, see PUBLISHING.md.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make changes following the existing patterns
4. Add tests for new functionality
5. Run tests: npm test
6. Submit a pull request

Code Style

• Follow TypeScript best practices
• Use meaningful names for variables, functions, and classes
• Keep functions small and single-purpose
• Add JSDoc comments for public APIs
• Follow clean architecture principles

License

MIT License - see LICENSE file for details.