How to Embed Cursor’s Composer Agent in Any Node.js Project with the New @cursor/sdk

Last night Cursor announced that its Composer Agent is now available as a TypeScript‑native npm package, @cursor/sdk, which can be added to any Node.js project instead of being limited to the Cursor IDE. npm install @cursor/sdk The release includes three items: the npm package itself, a documentation site at cursor.com/docs/sdk/typescript that explains the Agent lifecycle, streaming events, MCP integration and error types, and an open‑source github.com/cursor/cookbook repository containing four starter projects (Quickstart, Coding Agent CLI, a web‑based prototyping tool, and an Agent‑driven Kanban board). Early customers such as Rippling, Notion, C3 AI and Faire are already using the SDK for varied purposes, from backend agents to bug‑handling workflows and CI/CD automation. Pricing follows the existing token‑based model and usage appears on the team dashboard with an SDK tag.

What the SDK actually provides

The package exports Agent, which can be imported with: import { Agent } from "@cursor/sdk"; Creating an agent is done via Agent.create. The local field runs the agent in the current Node process, while the cloud field runs it in an isolated VM on Cursor’s infrastructure. The two modes share the same API; only the runtime configuration differs.

A minimal “Hello World” example from the docs looks like this:

import { Agent } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

const run = await agent.send("Summarize repository");
for await (const event of run.stream()) {
  console.log(event);
}

Key details: Agent.create is the entry point; local: { cwd } runs the agent locally, while cloud triggers remote execution.

The model.id field selects the underlying LLM – currently Composer‑2, Claude series, or GPT series. To enable the “thinking” mode you can pass additional parameters:

model: { id: "composer-2", params: [{ id: "thinking", value: "high" }] }

Available model IDs can be listed programmatically with Cursor.models.list(), which returns the models bound to your account. run.stream() yields a discriminated‑union of event types such as system, user, assistant, thinking, tool_call, status, task, request. If you prefer a single result you can call await run.wait() to obtain the final output, token usage and git metadata.

For one‑off prompts you can use the shorter helper:

const result = await Agent.prompt("Your question", options);

The SDK leverages the ES2024 await using construct so that an agent is automatically cleaned up when its scope ends:

await using agent = await Agent.create({ /* … */ });
// block ends → agent is disposed

The architecture diagram (shown below) clarifies the stack: the bottom layer lists the supported models (Composer, Claude, GPT, etc.), the middle “Harness” layer contains the Agent loop and MCP/Tools integration, and two execution paths sit on top – Managed Cloud adds a sandbox layer, while Local Workstation runs directly on the developer’s machine.

The key takeaway is that Local and Cloud share the same Harness, meaning code written for a local agent can be moved to the cloud simply by changing the configuration passed to Agent.create. Cloud mode provisions an isolated VM, clones the repository, runs a full dev environment, can create branches, push PRs and attach artifacts; it also survives network interruptions. Local mode, by contrast, runs in‑process and is suited for quick scripts or sensitive code that must stay on the developer’s machine. Note that artifact download ( downloadArtifact) is only available in cloud mode.

Configuration system – the real moat

The SDK’s power lies in its flexible configuration. The MCP server merges settings from five sources, ordered by priority: inline definitions in send(), inline definitions in create(), Cursor plugins, project‑level .cursor/mcp.json, and user‑level ~/.cursor/mcp.json. Inline send() definitions replace rather than merge, so developers must be aware of that behavior. Cloud agents can reuse OAuth tokens authorized on cursor.com, avoiding extra auth steps.

Skills are loaded from the .cursor/skills/ directory, Hooks are configured via .cursor/hooks.json, and Subagents can be defined by nesting agents fields. This means configurations created in the Cursor IDE are directly reusable through the SDK without duplication.

Error handling is granular: all exceptions inherit from CursorAgentError and expose an isRetryable flag. Specific error subclasses include AuthenticationError, RateLimitError, ConfigurationError, NetworkError, and UnknownAgentError. Before invoking an operation you can check support with run.supports(operation) to avoid unsupported calls.

Four Cookbook projects

Quickstart : a minimal Node.js example that demonstrates creating an agent and consuming streaming events.

Coding Agent CLI : an interactive terminal agent similar to Claude Code, fully open‑source and customizable (prompt, default model, team‑specific tools).

Prototyping Tool (app‑builder) : a web app that launches agents in a cloud sandbox for rapid prototype iteration, akin to a simplified Bolt framework.

Agent Kanban : a visual board that treats Cloud Agents as cards, grouping them by status or repository, previewing artifacts and spawning new agents – a collaborative workflow layer rather than a single‑user tool.

All four projects are written in TypeScript (≈95 % of the code), with only minor CSS/JavaScript components.

When to adopt the SDK now

Based on the announcement and early customer use‑cases, the most mature scenarios are:

CI/CD integration : attach an agent to PR checks to auto‑summarize changes, locate CI failures, or even generate a fixing commit (used by Faire).

Ticket‑to‑PR automation : trigger a Cloud Agent from a bug‑tracking system to read context, locate code, write a patch and open a PR (pursued by Notion and Rippling).

Embedding the agent in a product : expose an “AI assistant” button in a SaaS offering that runs a Cursor Agent behind the scenes.

No‑code Agent platform for non‑technical teams : front‑end forms or drag‑and‑drop interfaces launch agents that perform GTM or operations tasks, leveraging full code‑understanding rather than simple data queries.

Compared with other offerings (Anthropic’s Claude Agent SDK, OpenAI’s Agents SDK, Google’s Agent framework), Cursor’s differentiator is that it packages the entire Agent runtime—including context management, tool calls, sub‑tasks, and hooks—rather than merely wrapping a model API.

Before integrating, teams should consider vendor lock‑in, token cost, and the ROI of Composer‑2 versus their existing models. The SDK answers the “can it work?” question; the “is it worth it?” question requires a benchmark.

The pragmatic advice for Node.js/TypeScript developers is to run the Quickstart, explore the four cookbook projects, and keep the SDK as a ready‑to‑use option for future automation needs.