Cursor Agent

Cursor uses Cursor Agent’s HTTP/2 full-duplex Connect protocol at https://api2.cursor.sh/agent.v1.AgentService/Run.

Account and authentication

The local setup UI guides Cursor authorization, refreshes the account catalog, and lets you select parameter variants. The container owns its login independently of host applications.

Use a Cursor account:

claude-code-proxy cursor auth login
claude-code-proxy cursor auth status

The browser flow stores proxy-owned tokens. It does not read Cursor Agent’s Keychain or auth.json. CCP_CURSOR_AUTH_TOKEN can supply a bearer token directly to the proxy process.

Native protocol

The provider speaks Cursor’s protocol directly using Rust protobuf definitions. It does not run agent for inference or load its JavaScript bundle. An installed cursor-agent supplies the detected client version; CCP_CURSOR_CLIENT_VERSION can override it.

Models and modes

Prefer prefixed IDs:

• cursor:<model-id> runs the named Cursor model in agent mode.
• cursor-plan:<model-id> uses plan mode.
• cursor-ask:<model-id> uses ask mode.

Legacy IDs such as cursor, cursor-plan, cursor-ask, composer-2.5, and composer-2.5-fast remain available. Prefixes avoid collisions, so gpt-5.2 can route to Codex while cursor:gpt-5.2 routes to Cursor.

The proxy queries Cursor’s authenticated GetUsableModels and AvailableModels services. The first supplies account model aliases; the second supplies family IDs and exact parameter variants. Models that appear only in the wider metadata catalog are not advertised for your account. Use:

claude-code-proxy models --full

Unknown future IDs are accepted through cursor:<raw-model>.

Discovery is cached in memory for ten minutes and retried after thirty seconds on failure. A failed refresh can reuse the last successful catalog only for the same credential and endpoint. Account changes, logout, and authentication rejection clear the cached choices. Discovery failure does not prevent other providers from starting.

Start Claude Code with Cursor models

The getting started recipe uses cursor:gemini-4-argon[reasoning_effort=high] for the main conversation and Sonnet role, cursor:claude-opus-5-5[context=1m,effort=high,fast=false] for Opus, and cursor:grok-4.7-high-fast for Haiku background tasks. All roles use the same Cursor account. The configuration guide includes the full command and explains shell quoting.

After upgrading, restart the proxy process serving Claude Code. A fresh CLI catalog does not update an older listener. See the stale listener check.

Model parameters and context

Aliases are resolved using the catalog’s family ID, max mode flag, and complete parameter tuple. The proxy does not infer effort, speed, or context from a model’s name. A legacy alias can have both normal and max context variants; its default follows Cursor’s selection order.

For an explicit selection, copy a bracket variant from models --full, for example:

cursor:gpt-5.6-sol[context=272k,reasoning=high,fast=false]

Only advertised parameter combinations are accepted. Unknown future plain IDs are forwarded unchanged without invented parameters. Bracket selections require a discovered account catalog.

Display names supplied by Cursor can mention 1M even when an alias selects a smaller context. Gateway labels show the selected context parameter when known. A trailing [1m] is a separate Claude Code compaction hint; it never selects an upstream Cursor context variant. Match Claude Code’s compaction settings to the actual selection.

Picker discovery and Claude Code’s model capability recognition are separate. Custom gateway IDs may emit [claude-code:unrecognized_model] and use a 200K client context window. That is conservative for the account catalog observed during verification, but it does not enable a larger upstream window. See Claude Code’s context guidance for gateway and custom model IDs.

Claude Code model picker

Enable CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 when starting Claude Code with ANTHROPIC_BASE_URL pointing at the proxy. The HTTP catalog exposes one entry per distinct upstream model, max mode flag, and parameter tuple. Explicit parameter selections are preferred over duplicate aliases. Labels with otherwise identical names show the differing parameters, such as Composer’s fast=true and fast=false choices.

Gateway IDs use the readable claude-cursor:<raw model selection> form, preserving the catalog’s explicit parameters. Choose by label in /model, or copy an exact advertised id from /v1/models for scripts.

For a temporary switch, highlight the desired row in /model and press s; pressing Enter or typing /model <id> also saves the choice as the default for future sessions. See Claude Code’s model settings.

/model

Raw IDs and synonym aliases remain valid for API requests, --model, and ANTHROPIC_MODEL. For example, the observed selections cursor:composer-2.5[fast=false], cursor:gemini-3.7-flash[effort=high], and cursor:gpt-5.6-sol[context=272k,reasoning=high,fast=false] retain their exact parameters. Use the advertised gateway IDs for in-session switches.

Changing the selected model preserves Claude Code’s portable conversation history. It opens a new Cursor run rather than resuming a parked run belonging to another model, parameter selection, mode, credential, or endpoint.

Tools and multimodal input

• System prompts, messages, and tool definitions are rendered into the Cursor agent prompt.
• Base64 user images become Cursor selected images.
• Text, thinking, plan mode, ask mode, and usage stream back to Claude Code.
• The native tool bridge recognizes Cursor requests for Read, Write, and Bash when matching Claude tools are advertised and a Claude Code session ID is present. It pauses the stream, emits an Anthropic tool call, accepts the next tool result, and resumes stored events.
• Other Cursor workspace callbacks and native tool forms do not have a general Claude tool bridge.

OpenAI-compatible APIs

When the OpenAI routes are enabled, Cursor models work with both POST /v1/chat/completions and POST /v1/responses. To use the Read, Write, or Bash tool bridge, send stream: true, define the matching function tools, and include a stable session header. The proxy accepts x-claude-code-session-id, session_id, or x-client-request-id. Other function names are not supported by the Cursor bridge.

Session continuation

The proxy keeps a pending native tool run open across Claude Code requests carrying the same session identity. The tool result returns to that run on its existing stream. New turns use Claude Code’s rendered conversation history. Restarting the proxy clears pending runs; arbitrary Cursor chat ID resume metadata is not supported.

Configuration and troubleshooting

For an opt-in live check, start the authenticated proxy and run:

python3 scripts/test-cursor-claude --help

Supply at least two advertised --model IDs and an empty --output-dir. The script uses Python’s standard library and the installed Claude Code CLI. It consumes Cursor quota while checking model switches in one Claude session, actual Read, new-file Write, and Bash results, and a natural edit with a verification command. It retains evidence and returns a nonzero exit status on failure. The test process uses safe mode and an explicit tool allowlist; regular launches can retain your existing Claude Code hooks, skills, and settings.

CCP_CURSOR_BASE_URL and CCP_CURSOR_CLIENT_VERSION override protocol details. The old CCP_CURSOR_AGENT_BUNDLE setting is accepted for configuration compatibility but is unused by the native provider. If authentication cannot be refreshed, run claude-code-proxy cursor auth login again. A failed catalog query is reported while other providers remain available; account model access still depends on Cursor’s current policies and quotas.

See Compatibility and limitations for the supported tool boundary.