Cursor Internals Skill

Purpose

Specialized knowledge of Cursor IDE's internal architecture, authentication system, API structure, and cursor-agent CLI behavior discovered through reverse engineering.

When to Use

Integrating with Cursor's backend API
Understanding Cursor's authentication flow
Discovering and testing API endpoints
Troubleshooting authentication issues
Finding protobuf message definitions
Building tools that interact with Cursor's services
Working with cursor-agent CLI

Note: For database operations, schema details, and complete data structures, see the cursor-db skill.

Quick Start

Authentication Overview

Cursor uses Auth0 OAuth for authentication with JWT bearer tokens.

Key URLs:

Auth: https://authentication.cursor.sh
API: https://api2.cursor.sh
Telemetry: https://api3.cursor.sh

Required Headers:

http

Authorization: Bearer <jwt_token>
Content-Type: application/json
X-Cursor-User-Id: auth0|user_<identifier>
X-Cursor-Client-Version: 2.0.69

Capturing Your Token

Tokens are stored in-memory only, not on disk. Capture via HTTPS interception:

bash

cd ~/Documents/github/blink/tools
./capture_cursor_auth.sh

Tool will guide you through:

Installing mitmproxy
Installing SSL certificate
Proxying Cursor traffic
Extracting token from logs

Token location after capture: tools/.cursor_token (git-ignored)

Architecture Deep Dive

Dual Protocol System

Cursor's API uses two different protocols depending on endpoint complexity:

1. JSON Endpoints (Simple Queries)

Work with plain HTTP/JSON - accessible via curl/requests.

Working Endpoints:

/aiserver.v1.AiService/AvailableModels - List 40+ AI models
/aiserver.v1.AiService/GetDefaultModel - Get default model
/aiserver.v1.AiService/CheckFeaturesStatus - Feature flags
/aiserver.v1.AiService/KnowledgeBaseList - Knowledge bases
/aiserver.v1.AiService/CheckNumberConfig - Usage quotas
/aiserver.v1.AiService/AvailableDocs - Documentation sources

Characteristics:

Accept: application/json
Simple request/response
POST method with empty body {}
No streaming

2. Protobuf Endpoints (Complex Operations)

Require Protocol Buffers encoding via gRPC.

Endpoints (Not accessible via plain JSON):

/aiserver.v1.AiService/GetCompletionStream - Chat/completions
/aiserver.v1.ToolCallEventService/SubmitToolCallEvents - Tool calls
/aiserver.v1.AnalyticsService/Batch - Analytics
/aiserver.v1.AiService/CheckQueuePosition - Queue status

Characteristics:

Content-Type: application/proto
Binary protobuf encoding
Streaming support (SSE)
Connect-RPC protocol
User-Agent: connect-es/1.6.1

Network Stack

Cursor IDE (Electron)
    ↓
connect-es (gRPC-Web Client)
    ↓ 
HTTP/2 + Protocol Buffers
    ↓
api2.cursor.sh (AWS us-east-1)
    ↓
AI Providers (Anthropic, OpenAI, etc.)

Database

For complete database documentation, see the cursor-db skill.

Quick Reference

Location: ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb

Key Patterns:

composerData:{uuid} - Chat metadata
bubbleId:{composer}:{uuid} - Individual messages

Important: Database operations require understanding the complete 69+ field bubble structure. See cursor-db skill for:

Complete schemas
Required fields for IDE compatibility
Query patterns
Write best practices
Troubleshooting guides

Machine Identifiers

Cursor tracks three machine identifiers:

Storage location: ~/Library/Application Support/Cursor/User/storage.json

IDs:

telemetry.machineId - Machine identifier
telemetry.devDeviceId - Device UUID
telemetry.macMachineId - Mac-specific ID

Extraction script:

bash

cd ~/Documents/github/blink/tools
python3 extract_cursor_auth.py

Output: cursor_auth_data.json with all IDs

Authentication System

Token Structure

Format: JWT (JSON Web Token) Algorithm: HS256

Payload:

json

{
  "sub": "auth0|user_<identifier>",
  "time": "timestamp",
  "randomness": "uuid",
  "exp": 1767531038,
  "iss": "https://authentication.cursor.sh",
  "scope": "openid profile email offline_access",
  "aud": "https://cursor.com",
  "type": "session"
}

Expiration: Typically 53-60 days

Token Capture Process

Install mitmproxy: brew install mitmproxy
Generate certificate: Run mitmproxy once
Install cert: Add to macOS System Keychain
Proxy Cursor: Set HTTP_PROXY and HTTPS_PROXY
Use Cursor: Chat feature generates API calls
Extract token: From Authorization header in logs

Automated script: tools/capture_cursor_auth.sh

Token Storage

Local storage:

NOT in plain text files
NOT in database
NOT in keychain
Only in memory during runtime

After capture:

Stored in tools/.cursor_token (git-ignored)

Use environment variables:

bash

export CURSOR_AUTH_TOKEN="$(cat tools/.cursor_token)"
export CURSOR_USER_ID="auth0|user_<your_id>"

Working with the API

Python Example

python

import requests
import os

class CursorAPI:
    def __init__(self):
        self.base_url = "https://api2.cursor.sh"
        self.token = os.getenv('CURSOR_AUTH_TOKEN')
        self.user_id = os.getenv('CURSOR_USER_ID')
        
    def _headers(self):
        return {
            "Authorization": f"Bearer {self.token}",
            "Content-Type": "application/json",
            "X-Cursor-User-Id": self.user_id,
            "X-Cursor-Client-Version": "2.0.69"
        }
    
    def list_models(self):
        """Get all available AI models"""
        response = requests.post(
            f"{self.base_url}/aiserver.v1.AiService/AvailableModels",
            headers=self._headers(),
            json={}
        )
        return response.json()
    
    def check_features(self):
        """Check enabled features"""
        response = requests.post(
            f"{self.base_url}/aiserver.v1.AiService/CheckFeaturesStatus",
            headers=self._headers(),
            json={}
        )
        return response.json()
    
    def get_quotas(self):
        """Check usage quotas"""
        response = requests.post(
            f"{self.base_url}/aiserver.v1.AiService/CheckNumberConfig",
            headers=self._headers(),
            json={}
        )
        return response.json()

# Usage
api = CursorAPI()
models = api.list_models()
print(f"Found {len(models['models'])} models")

Available AI Models

Cursor provides access to 40+ AI models:

Cursor's Own:

composer-1 - Cursor's agentic coding model (200k context)
default - General model

Claude (Anthropic) - 8+ variants:

claude-4.5-sonnet - Latest model (200k context)
claude-4.5-sonnet-thinking - With reasoning
claude-4.5-haiku - Fast and cheap
claude-4.1-opus - Most powerful
Plus thinking and legacy variants

GPT-5 (OpenAI) - 15+ variants:

gpt-5 - Latest flagship
gpt-5-codex - Coding specialist
gpt-5-codex-high - High reasoning
gpt-5-fast - Priority processing (2x cost)
Multiple reasoning levels (low/medium/high)

Reasoning Models:

o3 - Deep reasoning
o3-pro - Most complex reasoning

Google:

gemini-2.5-pro - 1M context
gemini-2.5-flash - Fast variant

Others:

grok-4 (xAI)
grok-code-fast-1 - Free during promo
deepseek-r1, deepseek-v3.1
kimi-k2-instruct

Cursor-Agent CLI Deep Dive

Understanding cursor-agent Behavior

Installation:

bash

curl https://cursor.com/install -fsS | bash

Command Types:

create-chat - Generates chat ID only

bash

cursor-agent create-chat
# Returns: uuid (e.g., 3f1a6a8c-58d1-4fbe-81f7-1ad946d9c84e)
# NOTE: Does NOT create database entry - entry created on first message

Sending Messages - Uses --resume flag

bash

cursor-agent --print --force --resume <chat_id> "Your prompt"
# Automatically includes ALL chat history
# Writes both user and assistant messages to database
# Creates composerData entry if it doesn't exist

Critical Discovery: Database Entry Creation

Important: cursor-agent create-chat ONLY generates a UUID. The actual database entry is created when:

First message is sent via cursor-agent
OR manually created via direct database write

Implication for REST APIs:

After calling /agent/create-chat, the chat doesn't exist in database yet
Sending a message to a "created" chat will fail with 404
Solution: Auto-create composerData entry on first message if missing

For complete database structure requirements and investigation tools, see the cursor-db skill.

Quick Reference

Environment Setup

bash

# Set credentials
export CURSOR_AUTH_TOKEN="<your_token>"
export CURSOR_USER_ID="auth0|user_<your_id>"

# Or load from file
export CURSOR_AUTH_TOKEN="$(cat tools/.cursor_token)"

API Call Template

bash

curl -X POST https://api2.cursor.sh/aiserver.v1.AiService/<EndpointName> \
  -H "Authorization: Bearer $CURSOR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Cursor-User-Id: $CURSOR_USER_ID" \
  -H "X-Cursor-Client-Version: 2.0.69" \
  -d '{}'

Status Codes

200 - Success
401 - Unauthorized (bad token)
403 - Forbidden (expired token)
404 - Not found (or protobuf required, or chat doesn't exist)
429 - Rate limited
503 - Service unavailable

Progressive Disclosure

Basic (Start Here)

Cursor uses OAuth/Auth0 authentication
Two API types: JSON (simple) and Protobuf (chat)
Token capture via mitmproxy
40+ AI models available

Intermediate

Connect-RPC protocol for protobuf
SQLite database structure
Machine identifiers
Working code examples

Advanced

Protobuf definition discovery
gRPC reflection attempts
Binary traffic decoding
Custom gRPC client implementation

External Resources

Connect-RPC: https://connectrpc.com/
Protocol Buffers: https://protobuf.dev/
gRPC: https://grpc.io/
mitmproxy: https://mitmproxy.org/
Auth0: https://auth0.com/docs

Search AI Tools

cursor-internals

Install this agent skill to your Project

SKILL.md

Cursor Internals Skill

Purpose

When to Use

Quick Start

Authentication Overview

Capturing Your Token

Architecture Deep Dive

Dual Protocol System

1. JSON Endpoints (Simple Queries)

2. Protobuf Endpoints (Complex Operations)

Network Stack

Database

Quick Reference

Machine Identifiers

Authentication System

Token Structure

Token Capture Process

Token Storage

Working with the API

Python Example

Available AI Models

Cursor-Agent CLI Deep Dive

Understanding cursor-agent Behavior

Critical Discovery: Database Entry Creation

Quick Reference

Environment Setup

API Call Template

Status Codes

Progressive Disclosure

Basic (Start Here)

Intermediate

Advanced

External Resources