Cursor Sdk Typescript Agent Deployment

Date: 2026-05-12
Track: sandbox-poc
Slug: cursor-sdk-typescript-agent-deployment
Environment: macOS Darwin 24.6.0, Node.js v25.9.0, npm 11.12.1

Objective

Verify that the @cursor/sdk npm package exists, is installable, and inspect its public API surface. Document what is accessible without a Cursor API key (unauthenticated inspection).

Commands Run

1. npm search verification

npm search "@cursor" --json

Output (relevant):

@cursor/sdk - TypeScript SDK for Cursor agents.

Package confirmed present on npm registry.

2. npm info

npm info @cursor/sdk --json

Key output:

{
  "name": "@cursor/sdk",
  "version": "1.0.12",
  "description": "TypeScript SDK for Cursor agents.",
  "dist-tags": { "latest": "1.0.12" },
  "versions": ["1.0.8", "1.0.9", "1.0.10", "1.0.11", "1.0.12"],
  "homepage": "https://cursor.com",
  "repository": "git+https://github.com/cursor/cursor.git",
  "license": "SEE LICENSE IN LICENSE.md",
  "dependencies": {
    "@bufbuild/protobuf": "1.10.0",
    "@connectrpc/connect": "^1.6.1",
    "@connectrpc/connect-node": "^1.6.1",
    "@statsig/js-client": "3.31.0",
    "sqlite3": "^5.1.7",
    "zod": "^3.25.0"
  },
  "exports": [".", "./agent"]
}

Published date of v1.0.12: 2026-05-01T18:13:15.076Z

3. Installation

mkdir -p /tmp/cursor-sdk-sandbox
cd /tmp/cursor-sdk-sandbox
npm init -y
npm install @cursor/sdk

Output:

added 131 packages, and audited 132 packages in 8s
13 packages are looking for funding
10 vulnerabilities (2 low, 1 moderate, 7 high)

Result: Install succeeded. 131 packages total (SDK + transitive deps).

Vulnerabilities note: 10 vulnerabilities reported (2 low, 1 moderate, 7 high). These are standard audit findings from the dependency tree (sqlite3, protobuf). Not unusual for a public beta SDK. Recommend npm audit before production use.

4. Public API inspection (no API key required)

const { Agent, Cursor } = require('@cursor/sdk');

// Agent static methods
Object.getOwnPropertyNames(Agent)
  .filter(k => !['length','name','prototype'].includes(k))
// → ['create', 'resume', 'prompt', 'list', 'listRuns', 'getRun', 
//    'get', 'archive', 'unarchive', 'delete', 'messages']

// Cursor static methods
Object.getOwnPropertyNames(Cursor)
  .filter(k => !['length','name','prototype'].includes(k))
// → ['me', 'models', 'repositories']

Result: Import and class inspection worked without authentication.

5. Type definitions (from dist/esm/index.d.ts)

Key exported types confirmed:

• AgentDefinition, AgentOptions, LocalAgentOptions, CloudAgentOptions
• ModelSelection, ModelListItem, ModelVariant
• Run, RunResult, RunStatus, RunLifecycleStatus
• McpServerConfig
• Tool types: ReadToolCall, WriteToolCall, ShellToolCall, GlobToolCall, GrepToolCall, TaskToolCall, SubagentBackgroundReason
• InteractionListener, InteractionUpdate (streaming deltas)

What Worked

• npm search: confirmed package exists
• npm install: successful (131 deps)
• CJS require: Agent, Cursor classes accessible
• Type inspection: full API surface visible from .d.ts files
• Agent static methods: create, resume, prompt, list, listRuns, getRun, get, archive, unarchive, delete, messages
• Cursor static methods: me, models, repositories

What Failed / Limitations

• No API key available: Could not run an actual agent. Agent.create() and authenticated calls require CURSOR_API_KEY.
• 10 npm audit vulnerabilities: Not a blocker for development but worth noting for production. Most stem from the sqlite3 native dependency used for local run event storage.
• ESM import in Node: The exports field uses ESM-first. CJS interop worked in Node.js v25.9.0 via the require fallback, but ESM projects will need import { Agent } from "@cursor/sdk".
• self-hosted mode: Not tested. Requires a self-hosted runner binary (separate install).

Conclusion

@cursor/sdk v1.0.12 is a real, installable npm package released 2026-05-01. The API surface matches the official documentation: Agent.create() for local/cloud agents, Cursor.models() for model listing, hooks via .cursor/hooks.json, and MCP server config support. Content is safe to publish as a source-based guide with PoC install verification.