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

$3

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:

`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.

$3

For development or standalone usage:

1. Clone the repository:
`bash
git clone
cd cursor-background-agent-mcp
`

2. Install dependencies:
`bash
npm install
`

3. Set environment variables:
`bash
export CURSOR_API_KEY="your-cursor-api-key"
`

4. Build the project:
`bash
npm run build
`

5. Run as MCP STDIO server:
`bash
npm run mcp
`

Or run as HTTP server:
`bash
npm start
`

Usage

$3

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
`

$3

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

$3

#### launchAgent
Start a new background agent to work on a repository.

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

Output:
`json
{
"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:
`json
{
"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:
`json
{
"models": [
{ "name": "gpt-4", "recommended": true },
{ "name": "gpt-3.5", "recommended": false }
]
}
`

#### addFollowup
Send additional instructions to a running agent.

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

#### getAgentConversation
Retrieve conversation history of an agent.

Input:
`json
{
"agentId": "bc_abc123"
}
`

#### getAgentStatus
Get current status and results of an agent.

Input:
`json
{
"agentId": "bc_abc123"
}
`

Development

$3

`bash


Run all tests

npm test

Run tests in watch mode

npm run test:watch

Run tests with coverage

npm run test:coverage
`

$3

`
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
`

$3

1. Define the tool schema in src/domain/manifest.ts:
`typescript
{
name: "newTool",
description: "Description of the new tool",
inputSchema: { / JSON Schema / },
outputSchema: { / JSON Schema / }
}
`

2. Implement the tool logic in src/application/toolExecutionService.ts:
`typescript
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.

$3

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

`typescript
{
"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

$3

- 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.