Cursor Agent icon

Cursor Agent

Run Cursor Agent via the Cursor SDK (local runtime). Only User Message and Model are required; add Options for session, workspace, or MCP.

Cursor Agent

AI-generated

Summary

Runs a Cursor Agent (via @cursor/sdk, local runtime) for each input item with the given user message and model, and returns the agent's final markdown reply plus agent/run identifiers. Can optionally persist multi-turn sessions in Redis, set workspace directories and skills, attach MCP servers, and apply permission presets.

Inputs

  • chatInput (User Message) (required) — Prompt sent to the agent. An empty value throws an error for that item.
  • model — Cursor model id, loaded from Cursor.models.list() (falls back to composer-2.5/composer-2/composer-1 if listing fails). Defaults to composer-2.5.
  • systemMessage — System prompt. It is prepended to the user message (separated by '---') on the first turn only, and ignored when resuming a stored session. Presets mcp_skills_only and plan_only append extra permission instructions.
  • options.session.sessionId — Key mapping to a Cursor agentId in Redis. If one exists, the agent is resumed. Requires a Redis credential on the node, otherwise it errors.
  • options.session.sessionTtlSeconds — Redis TTL for the session mapping; default 604800 (7 days).
  • options.workspace — Skills Root Directory (placed first in cwd), Working Directories, legacy Working Directory, and Setting Sources (default project). If any is set, they are merged into the agent's local cwd, which falls back to process cwd if none is given.
  • options.agentBehavior.permissionPreset — full_agent (default), mcp_skills_only, plan_only, customer_service, or read_only. plan_only clears all MCP servers. mcp_skills_only and plan_only force the project setting source and rely on .cursor/cli.json under Skills Root. Sandbox is never enabled.
  • options.agentBehavior.maxTurns — Read but not wired into the Cursor SDK; has no effect.
  • options.mcp.mcpServers / mcpServersJson — MCP servers (HTTP, SSE or stdio) passed on create/resume and send. A non-empty JSON object keyed by server name overrides the form.
  • options.mcp.mcpToolAccess — Filter mode none, deny or allow, with tool name lists (plus an optional catalog for allow). Written into Skills Root/.cursor/cli.json as Mcp(server:tool) permissions. It only takes effect when Skills Root and at least one MCP server are set.

Output shape

One output item per input item, with json fields: output (markdown reply, with an embedded JSON block holding timeline, tool calls, thinking and suggestions, plus any suggestions), textOutput (clean final reply text), model, agentId, runId, and sessionId (if set).

The node needs a Cursor API credential (the CURSOR_API_KEY env var is a fallback), and an optional Redis credential. Only the last markdown segment of the run is returned as the reply. When n8n streaming is enabled, it also emits structured cursor JSON chunks (thinking, text, tool_start, tool_end, text_replace). A failed run or SDK error throws a NodeOperationError, which stops the node unless continue-on-fail is configured. The agent is disposed after each item. The session mapping is saved to Redis only after a successful run.

Examples

Example 1: One-off task with the default model

Set User Message to {{$json.question}} and leave Model at composer-2.5; read $json.textOutput downstream.

Example 2: Multi-turn chat bot

Add a Redis credential, set Options → Session → Session ID to {{$json.userId}}, and set a System Message for the first turn.

Example 3: Agent with skills and restricted MCP tools

Set Workspace → Skills Root Directory to /opt/skills, add an HTTP MCP server, set Permission Preset to MCP + Skills Only, and add an MCP Tool Filter in Allow List mode.

Links

Discussion