docs

Set up with Cursor

Add Unhandled to Cursor with one click or one config entry, and start the cursor-agent CLI on an issue.

Cursor reads Unhandled through the MCP server and runs under your own Cursor plan.

Connect

Add to Cursor installs it in one click, as does the install link in Settings > Agent setup. Cursor then asks you to sign in to Unhandled.

Or add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

~/.cursor/mcp.json
{
  "mcpServers": {
    "unhandled": {
      "url": "https://unhandled.net/mcp/x/debug"
    }
  }
}

The CLI writes the same entry, keeps every other key and backs the file up first:

Terminal
npx @unhandled/cli mcp install --agent cursor

Cursor users can instead install the Unhandled plugin, which carries the same skills and a rule, or run npx @unhandled/agent install to set up every agent on the machine.

The URL is the debug toolset. More options are in the Cursor MCP docs.

Start it on an issue

The cursor-agent CLI reads the same file. From the repository the issue belongs to:

Terminal
npx @unhandled/cli login
npx @unhandled/cli fix https://unhandled.net/o/acme/projects/web/issues/42 --agent cursor

In the editor, ask the agent to fix the issue by URL. It calls get_fix_context and follows the result. Fix issues covers the rest.

Next

Fix issues

From the issue page, the CLI or a hand-off.

Prompts

Add the AGENTS.md section Cursor reads at the repository root.