Cloud Agent

You run a Cloud MCP Server that lets Cursor Cloud Agents be created and managed programmatically. This server exposes a stable interface you can connect to from MCP clients, enabling automated task creation, repository interactions, and progress tracking across GitHub repositories.

How to use

You connect to the MCP server from a client and authorize with your API key. Choose the integration method you prefer: run the HTTP server locally or use a standard input/output (stdio) server for tight local workflows.

Typical workflow you’ll follow: discover your repository context, create a cloud task with a prompt, monitor its status, optionally send follow-up instructions, and review the resulting conversation or task output.

How to install

Prerequisites you need on your machine before starting the MCP server: Node.js and npm installed.

# Install the MCP server globally
npm install -g cursor-cloud-agent-mcp

# Set your API key for Cursor Cloud
export CURSOR_API_KEY=your_api_key_here

# Start the HTTP MCP server (default port 3000) and listen for connections
npm start

# Or start the stdio MCP server for local integrations
npm run start:stdio

Configuration and usage notes

Configure how you connect to the MCP server from your client. You can either point to the HTTP endpoint or run the stdio version locally and communicate via standard input/output.

HTTP server example you can use when you want a remote/machine-to-machine connection.

HTTP server connection (recommended for remote or remote-like setups)

Run the HTTP version locally to expose a web endpoint for MCP clients to reach.

Start the server and connect your MCP client to the following address.

STDIO server connection (local integrations)

Use the stdio server when you prefer process-based spawning and local integration within your development environment.

The runtime command and arguments shown below are the standard way to launch the stdio server via npm.

Security considerations

Protect your CURSOR_API_KEY as a secret and do not expose it in logs or shared configuration. Use environment-variable-based configuration in all deployment scenarios.

Troubleshooting tips

If the server does not start, verify Node.js and npm are installed, ensure your API key is set, and check that no other process is occupying port 3000. For stdio mode, confirm the process can communicate through standard I/O channels.

Examples of how to connect from clients

The following configurations illustrate how you can connect from MCP clients using either the HTTP endpoint or the stdio workflow. Use the method that matches your environment and tooling.

Notes on usage with the Cursor Cloud Agents API

This MCP server enables you to manage cloud agents that operate on GitHub repositories. You can run tasks, monitor progress, and retrieve conversation histories as part of an automated workflow.

Appendix: Examples of setup snippets

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

# Start HTTP server (default port 3000)
npm start

Available tools

get_repos

Detects current git repository information (URL, branch, uncommitted changes) and can list accessible repos when filtering is enabled.

get_me

Verify authentication and retrieve API key info.

get_models

List available LLM models.

create_task

Launch a cloud task with a given prompt and target repository.

list_tasks

List all cloud tasks for your account.

get_task

Get status of a specific task.

add_followup

Send additional instructions to a running task.

get_conversation

Retrieve full conversation history for a task.

delete_task

Permanently delete a task.