Cursor Agent

cursor-agent-mcp is a local stdio MCP server for the Cursor Agent CLI (agent). It lets MCP clients and AI coding agents delegate work to Cursor Agent while keeping the delegated run observable and recoverable.

It is meant to be a controlled harness around Cursor Agent, not a replacement for Cursor Agent itself. The server exposes MCP tools for model discovery, health checks, background jobs, log polling, result collection, output contract checks, write-scope reporting, and cancellation.

This is useful when an agent framework, local assistant, or automation system needs a Model Context Protocol server for Cursor Agent, a Cursor Agent CLI wrapper, or a Claude/Anthropic model handoff bridge with persisted job state.

Search terms that describe this project: MCP server, Model Context Protocol, Cursor Agent CLI, Cursor agentic CLI, Cursor CLI bridge, AI agent handoff, agent-to-agent delegation, Claude via Cursor, Anthropic via Cursor, background agent jobs, long-running agent task harness, persisted agent logs.

Status

Experimental but usable. The implementation was built for local agent-to-agent handoffs through the Cursor Agent CLI.

This project is unofficial and is not affiliated with Cursor, Anthropic, or OpenAI.

Requirements

• macOS, Linux, or another environment that can run Node.js and Cursor Agent.
• Node.js >=18.18.0.
• Cursor Agent CLI installed and available as agent.
• A logged-in Cursor Agent session.
• An MCP client that can launch stdio servers.

Check Cursor Agent locally:

agent --version
agent status
agent models

When This Fits

Use this server when an MCP client needs to:

• discover Cursor Agent models from the local agent models command;
• delegate a prompt to Cursor Agent from another local AI agent;
• start long-running Cursor Agent work as a recoverable background job;
• poll job status and tail stdout/stderr logs;
• collect a final result after the MCP client would otherwise have timed out;
• track files changed by a delegated run;
• apply expected-file or JSON-field output contracts;
• cancel Cursor Agent jobs and clean up child processes.

Do not use this as a hosted API or a remote multi-user service. It shells out to the local Cursor Agent CLI and uses the local Cursor account/session.

Install

Clone the repo and point your MCP client at the server entrypoint:

git clone https://github.com/ai-nuke/cursor-agent-mcp.git
cd cursor-agent-mcp
npm run smoke

For Codex, add something like this to ~/.codex/config.toml:

[mcp_servers.cursorAgent]
command = "/opt/homebrew/bin/node"
args = ["/absolute/path/to/cursor-agent-mcp/bin/cursor-agent-mcp.js"]
startup_timeout_sec = 90

If your node binary is elsewhere, use the absolute path from:

which node

Tools

• health_check: verifies DNS/HTTPS to Cursor backend, Cursor auth, model availability, restricted-mode setup, and an optional tiny write smoke test.
• list_models: returns agent models output plus inferred capability metadata.
• model_capabilities: returns inferred metadata for one model or all models.
• list_skills: asks Cursor Agent for its /skills output in a workspace.
• handoff: creates a persisted job. Read-only ask/plan jobs can wait briefly; edit-mode agent jobs return a job id by default.
• start_task: starts a background Cursor Agent job and returns immediately.
• list_jobs: lists recent and running jobs.
• job_status: reports elapsed time, output byte counts, changed-file counts, expected-file checks, and process ids.
• tail_job: reads stdout or stderr incrementally using byte offsets.
• job_result: returns final metadata, parsed Cursor Agent JSON when present, and stdout/stderr tails.
• cancel_job: cancels a running job and attempts process-tree cleanup.

Why Not Just Call agent --print Directly?

Direct synchronous calls are fragile for long tasks:

• MCP clients can time out while Cursor Agent keeps running.
• The caller can lose the job id and therefore lose access to stdout/stderr.
• Prompts passed as command-line arguments can leak through process listings.
• A prompt-level "write only here" instruction is not enforceable by itself.
• Retrying timed-out work can start two agents in the same directory.

This server wraps each Cursor invocation in a persisted job record before the process starts. Prompts are written to a per-job prompt file, logs are retained, background jobs can be polled, and the final result remains recoverable.

Runtime Files

Runtime metadata and logs default to:

/private/tmp/cursor-agent-mcp-jobs

Override this with:

CURSOR_AGENT_MCP_JOBS_DIR=/path/to/jobs node ./bin/cursor-agent-mcp.js

The server creates per-job Cursor config/data directories under the jobs directory. This avoids writing runtime state into the user's normal Cursor data folder while preserving Cursor CLI authentication.

Skill Files

Use skillFile to inject a task-specific SKILL.md-style file into the prompt passed to Cursor Agent. skillFile paths are resolved inside the workspace and are rejected if they escape the workspace.

Safety Features

• Background jobs by default for edit-mode agent tasks.
• Persisted job records for every launched Cursor Agent process.
• Prompt file indirection so the full prompt is not passed in argv.
• Exit code, signal, duration, and final status written to metadata.
• list_jobs, job_status, tail_job, job_result, and cancel_job.
• Lock keys and idempotency keys to avoid duplicate concurrent writes.
• Allowed write root validation and changed-file reporting.
• Expected-file and required-JSON-field contract checks.
• Optional post commands with cwd and command allow-list checks.
• Runtime watchdog via maxRuntimeMs.
• Process-tree cleanup on cancellation.
• Structured error categories such as dns, auth, quota, model_unavailable, timeout, agent_failed, contract_failed, and write_scope_violation.
• Restricted mode that launches Cursor Agent with isolated config/data dirs and an empty MCP config.

Known Limitations

• Model availability is whatever the local agent models command exposes for the current Cursor account. This may differ from Cursor Cloud Agent or Cursor editor model selectors.
• As of Cursor Agent CLI 2026.05.09-0afadcc, the local CLI exposed claude-4.6-sonnet-medium and claude-4.6-sonnet-medium-thinking, but not a local claude-4.6-sonnet-high-thinking model id. The MCP therefore refuses requiredThinkingLevel: "high" for claude-4.6-sonnet-medium-thinking. Cursor may expose Sonnet 4.6 High in other surfaces or future CLI versions; this server will only allow it when the local CLI reports that model.
• Thinking support is inferred from Cursor Agent model names because the CLI returns a human-readable model list rather than a formal capability schema.
• Write-scope enforcement is post-run detection and reporting, not a filesystem sandbox. The server can mark/report violations and optionally clean added files on failure, but it cannot prevent Cursor Agent from attempting writes.
• Restricted mode isolates Cursor Agent config/data directories for the job, but Cursor may still discover project-local configuration depending on the Cursor CLI implementation.
• job_result parses final JSON from Cursor Agent stdout when available. Non-JSON Cursor output is still returned as log tails.
• The health check uses api2.cursor.sh because that is the backend endpoint this harness currently probes. Cursor may change backend hostnames.
• The server shells out to local commands for post checks. Keep allowedPostCommands narrow for untrusted workspaces.

Development

Run the smoke test:

npm run smoke

Start the MCP server manually:

npm start

Use a different Cursor Agent binary:

CURSOR_AGENT_BIN=/path/to/agent npm start

Use a different default model:

CURSOR_AGENT_DEFAULT_MODEL=claude-opus-4-7-thinking-high npm start

License

MIT