Cursor

Start with a clear work item in One Horizon. The initiative, bug, or todo should give Cursor the goal, context, links, comments, and acceptance notes before it starts.

After that, choose how you want to work. Stay in Cursor with the MCP connector, or let a local Cursor agent run the task on your machine from Desktop, the CLI, or Workflows. Once the task has enough detail, there is no long prompt handoff to write.

Local agent setup is separate from the MCP connector. It needs the Cursor CLI as agent or cursor-agent; the editor MCP setup alone is not enough.

Choose how to use Cursor

Start with the work item

Cursor works best when the initiative, bug, or todo already explains the change. Add the outcome, important files or links, constraints, and what counts as done. That work item becomes the prompt source for both MCP chat and local agent runs.

For planned implementation work, keep the brief close to spec-driven development: specific enough for Cursor to act, short enough for a person to review.

Connect Cursor through MCP

MCP is the interactive path. Configure it when you want Cursor chat to read or update One Horizon work while you code.

The easiest setup path is the install button:

Manual installation

Configure the MCP server for yourself or for one project by creating a configuration file.

For all your projects

Create ~/.cursor/mcp.json in your home directory.

For one project

Create .cursor/mcp.json at your project root.

In either file, add this configuration:

{  "mcpServers": {    "one_horizon": {      "command": "npx",      "args": [        "mcp-remote@latest",        "https://mcp.onehorizon.ai/mcp"      ]    }  }}

Activate in Cursor

Open a chat in Cursor and enable the tool if it is not already active. Try asking "show my planned work for this week".

The first call may take a moment to load. Cursor prompts you to authenticate. Follow the browser window to sign in and authorize the connection.

What you can ask Cursor

Short prompts are enough when the work item already has the detail:

"show my assigned issues and todos for today"

Cursor pulls your in-flight issues from tools like Linear or Jira and summarizes them.

"use my assigned work details for the gateway API"

Cursor pulls those details into context so the AI writes code with the right scope and names.

"capture this as completed work"

Cursor summarizes what it wrote and adds a completed task.

Security and permissions

The connector acts on your behalf. Data access follows your roles, workspace membership, and granted scopes.

Run Cursor as a local agent

A local Cursor agent is for tasks you want Cursor to work through outside the editor chat. After setup, open an initiative, bug, or todo in One Horizon, choose Send to, and pick your Cursor agent. The run stays tied to that work item.

Local Cursor agents use the Cursor CLI, not the Cursor IDE MCP connector. Installing the editor and configuring MCP does not install or sign in the CLI.

Install the Cursor CLI

Check whether the CLI is already available in the terminal where you run one agent or start Desktop agents:

agent --version

Some installs expose cursor-agent instead of agent. Desktop setup checks for the same binary before it can start a Cursor agent.

If the command is missing, install the Cursor CLI:

curl https://cursor.com/install -fsS | bash

See the Cursor CLI installation page. If the installer puts agent in ~/.local/bin, add that directory to your PATH.

Sign in to the Cursor CLI

After install, authenticate the CLI before you set up a local agent. Signing in to Cursor MCP or the Cursor editor does not sign in the CLI.

agent statusagent login

Or set CURSOR_API_KEY from Cursor Settings → Integrations → User API Keys. One Horizon does not store Cursor credentials.

If a browser cannot open from the terminal, run NO_OPEN_BROWSER=1 agent login and open the printed URL yourself.

When authentication is missing, setup or a run may fail with:

Cursor CLI is not authenticated on this machine. Run agent login, or set CURSOR_API_KEY from Cursor Settings → Integrations → User API Keys, then retry.

Run one agent doctor to confirm the CLI is on PATH and authenticated before setup.

Set up in Desktop or the CLI

Desktop gives the guided setup path. Open Workflows, go to the agents page, select Add agent, and choose Cursor. Pick a runtime preset, set Agent access, choose the repository folder, and decide whether One Horizon should create PRs or MRs after successful runs. The same setup modal is available from an agent step in the workflow designer.

Start from the terminal when you want scriptable control:

one agent createone agent doctorone agent watch

A workflow can target the same local agent. Local Agents covers setup, run modes, worktrees, pull requests, artifacts, and safety boundaries.

For document-backed runs, the local agent temporarily adds one_documents to the task worktree's .cursor/mcp.json. The token is passed through ONE_WORKER_DOCUMENT_TOKEN, not written into that file. Cursor also reads its normal project and global MCP configuration, so review unrelated Cursor MCP servers before using local agents on sensitive repositories.

Agent Sessions covers the run lifecycle.

Troubleshooting