Cursor SDK: Build AI Coding Agents in TypeScript

When Cursor released its TypeScript SDK on April 29, 2026, it changed the framing of what a coding assistant is. Before the SDK, Cursor agents lived inside the IDE. After it, they're programmable infrastructure — agents you can invoke from a CI pipeline, a cron job, or a backend service with the same capabilities as the desktop app.

This guide covers what the Cursor SDK actually is, how its deployment model works, and how to wire it into real workflows. Effloow Lab verified that @cursor/sdk v1.0.12 is installable and inspected its public API surface as part of this write-up (see data/lab-runs/cursor-sdk-typescript-agent-deployment.md for the raw commands and outputs).

What the Cursor SDK Is (and Isn't)

The Cursor SDK (@cursor/sdk) is a TypeScript package that gives you programmatic access to the same agent runtime that powers the Cursor desktop app, CLI, and web interface. You get:

• Codebase indexing — the agent understands your repo structure out of the box
• Full tool access — read, write, glob, grep, shell, semantic search
• Model choice — Composer 2 (Cursor's in-house model), Claude Opus 4.7, GPT-5.5, Gemini 3.1 Pro, and others
• MCP server support — connect external tools over stdio or HTTP
• Hooks — lifecycle callbacks to observe, modify, or block agent actions
• Subagents — delegate subtasks to named sub-agents with different prompts and models

What it isn't: a general-purpose LLM client or a thin wrapper over the OpenAI API. The SDK is specifically built around the Cursor agent loop — the same harness that handles multi-step coding tasks with tool use, checkpointing, and repo context.

As of v1.0.12 (published 2026-05-01), the package has been in public beta for all users since launch.

Installation and Environment Setup

Installing the SDK is a single command:

npm install @cursor/sdk

The Effloow Lab sandbox confirmed this installs successfully on Node.js v25.9.0 with npm 11.12.1, pulling 131 packages total. The main dependencies are @bufbuild/protobuf and @connectrpc/connect (for the gRPC-based communication layer), sqlite3 (used to store local run events), and zod for schema validation.

One note from the sandbox run: npm audit reports 10 vulnerabilities (2 low, 1 moderate, 7 high) in the current dependency tree, mostly stemming from sqlite3's native bindings. This is common for public beta SDKs. Run npm audit before any production deployment and monitor for updates.

You'll also need a Cursor API key. Set it as an environment variable:

export CURSOR_API_KEY="your_key_here"

API keys are available from your Cursor account settings. The SDK reads CURSOR_API_KEY from the environment automatically, or you can pass it explicitly in the Agent.create() call.

The Agent API: Three Deployment Modes

The SDK exposes an Agent class with a static Agent.create() factory. The Effloow Lab inspection confirmed these static methods on the Agent class: create, resume, prompt, list, listRuns, getRun, get, archive, unarchive, delete, and messages.

The create call accepts three mutually exclusive deployment targets via the options object:

Mode 1: Local Agent

The agent runs on your machine, using your local filesystem. Good for one-off scripts, local automation, and development.

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 what this repository does and list its main entry points");

for await (const event of run.stream()) {
  if (event.type === "text-delta") {
    process.stdout.write(event.text);
  }
}

The run.stream() method yields typed InteractionUpdate events — text deltas, tool call starts and completions, thinking deltas, and shell output. This lets you build real-time UIs or pipe the output to logs without buffering the whole response.

Mode 2: Cloud Agent

Each cloud run gets its own sandboxed VM managed by Cursor. The VM clones the target repository, sets up the development environment, and continues running even if the invoking script exits. You can reconnect and stream the conversation later using Agent.resume().

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

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "claude-opus-4-7" },
  cloud: {
    repo: "github.com/your-org/your-repo",
    branch: "main",
  },
});

const run = await agent.send(
  "Review the changes in the last PR and open a follow-up issue for any technical debt introduced"
);

// Optionally stream, or fire-and-forget
const result = await run.wait();
console.log("Agent status:", result.status);

Cloud agents are the right choice for long-running tasks, CI-triggered workflows, or anything where you don't want the agent tied to a process lifecycle. The agent can push branches and open pull requests directly from the VM.

Mode 3: Self-Hosted Agent

You can run the agent runtime on your own infrastructure — useful for air-gapped environments or when you need to control where code is executed. Self-hosted mode requires a separate runner binary and additional setup documented in the Cursor SDK docs.

Hooks: Observing and Controlling the Agent Loop

Hooks let you intercept the agent at specific points in its execution loop. They're defined in .cursor/hooks.json at the repo root and apply across all three deployment modes.

{
  "hooks": [
    {
      "event": "onFileEdit",
      "command": "npx prettier --write {file}"
    },
    {
      "event": "beforeShellCommand",
      "command": "scripts/guard-destructive.sh {command}"
    },
    {
      "event": "onRunComplete",
      "command": "scripts/notify-slack.sh {runId} {status}"
    }
  ]
}

Common hook events include:

• onFileEdit — fires after each file write, useful for formatters and linters
• beforeShellCommand — runs before shell execution, good for safety guardrails
• onRunComplete — fires when the agent finishes, useful for notifications or post-processing
• onToolCall — fires on any tool use, giving you a full audit log

Hooks receive context variables like {file}, {command}, and {runId} as string interpolations in the command. The hook's exit code determines whether the agent proceeds (exit 0) or aborts the action (any non-zero exit).

Subagents: Multi-Agent Orchestration Without Custom Glue

Subagents let the main agent delegate subtasks to specialized agents. You define them either in .cursor/agents/*.md files or inline in the Agent.create() call:

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  agents: {
    "code-reviewer": {
      prompt: "You are a strict code reviewer focused on security and performance. Review changes and output a list of issues.",
      model: { id: "claude-opus-4-7" },
    },
    "doc-writer": {
      prompt: "You write concise, accurate technical documentation in Markdown.",
      model: { id: "composer-2" },
    },
  },
});

When the main agent calls the Agent tool with a name matching one of these definitions, the subagent runs as a separate call with its own prompt context and model. The main agent receives the subagent's output and continues. This is how teams build multi-step pipelines — review agent → fix agent → doc agent — without custom orchestration code.

MCP Server Integration

MCP (Model Context Protocol) servers extend the agent's tool set with external data sources and actions. You can configure them in .cursor/mcp.json or pass them directly to Agent.create():

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  mcpServers: [
    {
      name: "linear",
      transport: "stdio",
      command: "npx",
      args: ["-y", "@linear/mcp-server"],
      env: { LINEAR_API_KEY: process.env.LINEAR_API_KEY },
    },
    {
      name: "postgres",
      transport: "http",
      url: "http://localhost:8080/mcp",
    },
  ],
});

With MCP servers configured, the agent can query Linear for ticket context, pull database schemas, or call any custom tool you expose over the MCP protocol — without any special prompting. The agent discovers available tools automatically.

CI/CD Patterns

The most common production use case teams are building with the Cursor SDK is CI/CD integration. Here are three patterns that work today:

Pattern 1: PR Summary on Push

// ci/summarize-pr.ts
import { Agent } from "@cursor/sdk";

const prNumber = process.env.PR_NUMBER;
const branch = process.env.GITHUB_HEAD_REF;

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  cloud: { repo: process.env.GITHUB_REPOSITORY, branch },
});

const run = await agent.send(`
  Review the changes in PR #${prNumber} compared to main.
  Write a concise summary covering: what changed, why it matters, and any risks.
  Output as a GitHub comment body in Markdown.
`);

const result = await run.wait();
// Post result.output to the PR via GitHub API

Pattern 2: Auto-Fix CI Failures

// ci/fix-failures.ts
import { Agent } from "@cursor/sdk";
import { readFileSync } from "fs";

const failureLog = readFileSync("/tmp/ci-failures.txt", "utf-8");

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "claude-opus-4-7" },
  cloud: {
    repo: process.env.GITHUB_REPOSITORY,
    branch: `fix/auto-${Date.now()}`,
    baseBranch: process.env.GITHUB_HEAD_REF,
  },
});

const run = await agent.send(`
  The following tests are failing:\n\n${failureLog}\n\n
  Identify the root cause and apply the minimal fix.
  Push the changes and open a pull request with a description of what you changed and why.
`);

await run.wait();

Pattern 3: Scheduled Documentation Sync

// scripts/sync-docs.ts
import { Agent } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  cloud: { repo: "github.com/your-org/docs", branch: "main" },
});

await agent.send(
  "Review all public API functions in src/api/ for missing or outdated JSDoc comments. Update them to match the current implementation. Commit directly to main."
);

These patterns work because cloud agents persist independently — the CI runner just fires the Agent.create() call and optionally monitors the result. The actual work happens in Cursor's infrastructure.

Pricing Considerations

The Cursor SDK uses the same token-based pricing as Cursor's Max Mode. A few reference points from Cursor's published pricing:

• Auto mode (Cursor selects model): ~$0.25/M tokens (cache read), $1.25/M tokens (input), $6.00/M tokens (output)
• Claude Opus 4.7 and GPT-5.5 are frontier-tier models priced higher
• A complex task with 150 tool calls, 200K input tokens, and 20K output tokens costs roughly $3–8 depending on the model

Cloud agents also incur VM compute costs during execution. For typical CI tasks (PR summary, test fix), an agent run of 5–15 minutes will consume a manageable amount of tokens — but high-frequency automation on large repos can accumulate cost quickly. Start with composer-2 for volume use cases and reserve Opus 4.7 for tasks where accuracy matters most.

Strengths
<ul>
  <li>Same runtime as the desktop app — no capability gap between IDE and API agents</li>
  <li>Three deployment modes (local, cloud, self-hosted) in a single API surface</li>
  <li>Hooks and subagents enable complex pipelines without custom orchestration code</li>
  <li>MCP server support extends the agent's tool set to any external system</li>
  <li>Cloud agents persist independently of the invoking process</li>
</ul>


Limitations
<ul>
  <li>Public beta — API surface may change between minor versions</li>
  <li>10 npm audit vulnerabilities in v1.0.12 (monitor for fixes)</li>
  <li>Token-based pricing can accumulate at scale; no flat-rate option for SDK use</li>
  <li>Self-hosted mode requires a separate runner binary setup</li>
  <li>No offline or air-gapped cloud VM option; cloud mode phones home to Cursor infrastructure</li>
</ul>

What to Build First

If you're evaluating the Cursor SDK, the fastest path to value is a PR summary script. It's a contained task, produces immediately useful output, and doesn't require write access to your repo. From there, the escalation path is clear: CI failure diagnosis, documentation sync, and eventually multi-agent pipelines with subagents.

Rippling, Notion, Faire, and C3 AI are confirmed early adopters from the April 2026 launch announcement — all using cloud agents for CI/CD automation at various scales.

The SDK is in active development. Check the Cursor SDK changelog and the cursor/cookbook GitHub repo for recipes that the Cursor team adds as real-world patterns emerge.

Bottom Line

The Cursor SDK turns a coding assistant into programmable infrastructure. If your team already uses Cursor and runs any manual agent tasks on a schedule, this SDK makes those tasks repeatable, auditable, and composable. Start with cloud mode for CI/CD and move to subagents once the basic pattern works.

FAQ

Q: Do I need a Cursor Pro subscription to use the SDK?

You need a Cursor account with API access. As of the public beta, SDK usage is billed separately via token-based pricing, not against your plan's monthly request quota. Check your Cursor account settings for API key availability.

Q: Can I use the SDK without the Cursor desktop app installed?

Yes. The SDK is a standalone npm package. You don't need the desktop app on the machine running the agent. You do need a CURSOR_API_KEY and network access to Cursor's API endpoints.

Q: How does cloud agent persistence work if my script exits?

When you launch a cloud agent, Cursor's infrastructure takes ownership of the VM and the agent run. Your script can exit immediately after calling agent.send(). You can reconnect later with Agent.resume(agentId) and stream the conversation from wherever it left off.

Q: Are there rate limits on the SDK?

The SDK inherits Cursor's standard rate limits. High-frequency automation (many concurrent cloud agents) may hit limits. The Cursor.models() call returns the current model list, and responses include rate limit headers when limits are approached.

Q: What models are available?

Cursor.models() returns the full list of available models at runtime. At launch, this includes Composer 2, Claude Opus 4.7, GPT-5.5, Gemini 3.1 Pro, and additional frontier models as they become available inside Cursor.