Cursor Editor Setup

Connect QCode.cc to Cursor IDE with a custom Anthropic / OpenAI Base URL + API Key, including model config, custom-endpoint limitations, and troubleshooting

Last verified: 2026-09-18 · 📄 Per official docs (Cursor 3.21 (official download page, golden channel, checked 2026-09); the Override fields rest on a 2026-08-11 reply from Cursor staff on the official forum)

At a glance¶

Where the fields are, and a known bug¶

The place to type a URL is Settings → Models → API Keys. Cursor's BYOK help page (cursor.com/help/models-and-usage/api-keys) lists only four steps: open Cursor Settings → Models, pick the provider (OpenAI, Anthropic, Google, Azure or AWS Bedrock), paste your API key into the text field, click Save — it does not enumerate the override fields. The fields do exist; Cursor staff member deanrie named them in the official forum:

"The fix for the OpenAI API Key and Override OpenAI Base URL fields, and other provider key fields, that didn't focus on mouse click has been merged and will ship in an upcoming 3.15 update. It's not in 3.15.6 yet. Once you update to a version newer than 3.15.6, please try again." (2026-08-11, original thread)

Three actionable points:

• The fields are Override OpenAI Base URL (the OpenAI leg) and Override Anthropic Base URL (the Anthropic leg), each with its own enable toggle.
• 3.15.6 has a known regression: the mouse cannot focus those inputs. The official workaround is to turn on the relevant toggle in Settings → Models, then press Tab to move focus into the field — after that typing and Ctrl+V work. Rolling back to 3.14.27 also works. The fix ships in an update after 3.15.6, so upgrade past 3.15.6 and retry.
• The same page states, verbatim: "Your API key is not stored on our servers. It is sent to our backend with every request because all requests are routed through Cursor's servers for final prompt building" — even with your own key, requests pass through Cursor's backend; the editor does not talk to your model vendor directly.

Three more limits and one time risk:

• On Teams / Enterprise plans the Cursor Token Rate still applies even with your own key, and the OpenAI BYOK description is limited to "Standard, non-reasoning chat models".
• To keep traffic entirely off Cursor's backend you need a client that supports a custom Base URL: Claude Code, Codex CLI, Cline, Zed and similar.
• Time risk: in a statement dated 2026-08-28 OpenAI wrote that they "intend to wind down our contract providing OpenAI models to Cursor, with a proposed shutoff date of November 12, 2026" — proposed, not yet in force. Cursor has published no corresponding notice as of 2026-09-18. Source: openai.com.

Cursor is an AI-native editor built on top of VS Code. Cursor's changelog is not organised by version number, so this page does not repeat "release X added feature Y" narratives; what we could confirm is that the download page offered the 3.21 golden channel. This guide explains how to plug QCode.cc into Cursor — but read the next section first, because it decides whether this route works for you at all.

Why Use Cursor¶

• Agents Window (new in v3): run multiple AI agents in parallel in the sidebar without interference
• Cursor Composer: multi-file editing with context-aware refactoring, better suited than Cursor Chat for large changes
• Inline Edit (Cmd+K): select code and issue an instruction inline — the fastest iteration loop
• Built on VS Code: inherits the entire VS Code extension ecosystem (including the Claude Code VS Code extension)

Prerequisites¶

• Cursor installed (macOS / Windows / Linux)
• A QCode.cc API Key (starts with cr_), available from the dashboard
• The same API Key works across all QCode protocols and all four ingress domains (api / asia / us / eu); users in mainland China should prefer asia.qcode.cc

Available Models¶

The table below lists the model ids we commonly use on QCode (live list and prices on qcode.cc/models); these are exactly what you type into Cursor. Field locations and the 3.15.6 input bug are covered in the section above.

Gemini unit prices and any plan multiplier are whatever qcode.cc/models shows — do not reuse a verbal “×2”. The table above is the current recommendation; 4.x IDs such as claude-sonnet-4-6, claude-opus-4-8, and claude-opus-4-7 remain on sale.

Configuration Steps¶

The two paths below map onto the two Override fields; Path A (OpenAI protocol) has the best compatibility. If the inputs will not take focus, use the Tab workaround above or update past 3.15.6.

Path A: Custom OpenAI-compatible endpoint (recommended)¶

Use the OpenAI protocol to talk to QCode's /openai/v1 path, which serves GPT models and the four Chinese families (GLM / Kimi / DeepSeek / Qwen).

🔴 This leg cannot serve Claude, and cannot serve Gemini either. QCode's OpenAI endpoint accepts only those two groups; a claude-… or gemini-… id returns model_not_available_on_endpoint. For Claude, use Path B below. See Endpoints & API Paths.

1. Open Cursor settings: Cmd + , (macOS) / Ctrl + , (Windows/Linux)
2. Models → scroll to the bottom and find Override OpenAI Base URL
3. Fill in:

1. In the Models list, check the models you want to enable (e.g., gpt-5.5, gpt-5.4, gpt-5.6-terra); for any model not listed, click + Add model and enter the model id manually
2. Click Verify to test connectivity; once it passes, you can use it from Cursor Chat / Composer

The Base URL must not end with a trailing slash. A QCode self-check request returns 401, which means the path is correct and only auth is missing — this is normal and confirms the endpoint is reachable.

Base URL reference per protocol (the same Key works for all of them):

Path B: Custom Anthropic endpoint (native Claude protocol)¶

If you want to use the native Anthropic protocol for Claude models, QCode's Anthropic Base URL is https://api.qcode.cc/api (the SDK automatically appends /v1/messages).

In Cursor settings, open Models → Anthropic API, enter your QCode key, and turn on Override Anthropic Base URL with the address above.

🔴 The two overrides interfere with each other. As reported by users: once Override OpenAI Base URL is set, Cursor also routes Claude traffic to that OpenAI endpoint, and Claude models fail with 422. Cursor's documentation does not record this behaviour — it is a community observation and may change with versions. To use Claude, set only the Anthropic override and leave the OpenAI override empty. If you need both, use separate Cursor profiles or switch as needed.

⚠️ Under Agent mode some capabilities use an OpenAI Responses API style that is incompatible with the Anthropic protocol path in certain scenarios (typically failed schema conversion for some tool calls). Cursor's endpoint toggles change from time to time, so defer to Cursor's official docs.

Which Features Work Over a Custom Endpoint¶

Cursor splits its AI capabilities into several categories, and a custom OpenAI endpoint covers them to different degrees. The table below is a practical assessment based on current observation; Cursor updates frequently, so the final word is Cursor's official docs:

In short: the Chat / Composer / Inline Edit trio is the most reliable on a QCode endpoint; heavily managed features (Tab completion, parts of the agent flow) may stay on Cursor's own models. This whole section is observation, not official documentation — follow Cursor's announcements.

A Typical Workflow¶

Once the endpoint is set up, a day-to-day Composer flow looks roughly like this:

1. Pick a model in Composer (e.g., claude-sonnet-5 for everyday work, claude-opus-5 for big changes)
2. Open Composer with Cmd + I and drag the files you want to edit into the context area
3. Describe the goal in natural language, e.g. "migrate this component's state management from useState to useReducer, keeping the existing props unchanged"
4. Review the diff and Accept / Reject block by block
5. For quick local edits, use Inline Edit (Cmd + K) instead of opening Composer every time

This whole flow runs on the QCode endpoint you configured, and quota is settled per the Billing rules.

Fallback Endpoints¶

The four domains are different entry points to the same service, and the same API Key works on all of them. For the full reference, see Endpoints and API Paths.

Image Input vs. Image Generation¶

• Image input (let the model "see" an image): Cursor lets you paste or drag screenshots / design mockups into the conversation so a vision-capable model can read them — for example, building a component from a UI sketch or debugging from an error screenshot. Vision-capable models on QCode include Claude Opus 5 / Sonnet 5 and GPT-5.x.
• Image generation (let the model "draw"): this is a different thing. To generate images, use QCode's gpt-image-2 model over the dedicated image endpoint — not within the Cursor editor flow. See gpt-image-2 Image Generation.

Using Alongside Claude Code¶

Cursor's built-in AI does not conflict with the standalone Claude Code CLI — both can run side-by-side in the same Cursor window:

• Cursor Chat / Composer: in-editor AI that uses the endpoint configured in Cursor settings
• Claude Code CLI: run claude in Cursor's integrated terminal (Ctrl + `); it uses the CLI's own ANTHROPIC_BASE_URL environment variable

Point Claude Code at QCode (Anthropic protocol) from the integrated terminal:

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_key"
claude

The two paths authenticate independently, but using the same QCode API Key on both means shared quota (see Billing for details). Claude Code's Subagents and Automation & CI/CD both work directly in this terminal.

Limitations and Notes¶

• Privacy Mode: Cursor sends code snippets to the configured endpoint by default. If you have Privacy Mode enabled in Cursor settings, confirm that the API Key configuration still lets you reach QCode; Privacy Mode does not affect outbound traffic, it only blocks Cursor itself from storing your prompts
• A Cursor Pro subscription and a QCode API Key are two independent systems — Cursor Pro grants you Cursor's built-in quota (using Cursor's own model pool), while the QCode API Key uses our gateway pool. When both are active, routing follows the priority configured in Cursor
• Agents Window and background agents work best with mainstream providers (OpenAI / Anthropic protocols); self-hosted OSS model servers are hit and miss
• The override is a global switch: filling in Override OpenAI Base URL points the requests that default to the OpenAI protocol at QCode, and clearing it returns to Cursor's default. But per the official wording, requests still pass through Cursor's backend for prompt building, so the assumption "only the traffic moved, nothing else changed" does not hold

Practical Tips¶

• Pick a model per task: on Path B (Anthropic, https://api.qcode.cc/api), claude-sonnet-5 gives the best value for everyday editing and claude-opus-5 handles large refactors; on Path A (OpenAI), try gpt-5.6-terra for pure code completion and gpt-5.5 for general work
• Prefer the 1M tier for long context: 1M-context models like claude-opus-5 / gpt-5.5 suit Composer changes that feed in an entire repo
• Save money: set a mid-tier model as the Composer default and switch to a flagship manually only for hard problems
• Use the nearest endpoint: in mainland China, switching the Base URL to https://asia.qcode.cc/openai/v1 is usually faster
• Hit Verify first when behavior gets weird: endpoint behavior can change after a Cursor update, so click Verify once before chasing other issues

FAQ¶

Cursor reports "API key not valid"¶

1. Verify the API Key is complete, starts with cr_, and has no leading or trailing whitespace
2. Click Verify in Cursor settings to see the specific error
3. Test connectivity from the command line: bash curl -H "Authorization: Bearer YOUR_KEY" \ https://api.qcode.cc/openai/v1/models If the response is a JSON list, both the endpoint and the API Key are OK

Verify fails but curl works¶

This is usually a trailing slash on the Base URL or a path missing /v1. Confirm you entered https://api.qcode.cc/openai/v1 (OpenAI protocol) with no trailing /. Note: hitting the base path directly and getting 401 is normal (path correct, auth missing) and does not mean the config is wrong.

Composer cannot use Claude models¶

Composer defaults to the OpenAI protocol, and QCode's OpenAI endpoint does not accept Claude models — adding claude-opus-5 to the Models list will not help, because the request is rejected with model_not_available_on_endpoint.

Use Path B instead: in Models → Anthropic API, enter your QCode key, turn on Override Anthropic Base URL with https://api.qcode.cc/api, and clear Override OpenAI Base URL (otherwise Cursor sends Claude traffic to the OpenAI endpoint and returns 422).

Inline Edit (Cmd+K) is slow¶

Cursor's Cmd+K defaults to Cursor's own fast model; switching to QCode routes through the configured base URL, so first-token latency is slightly higher than Cursor's built-in option (one extra hop). In settings, you can keep Cursor Tab on Cursor's default while routing Chat / Composer through the QCode endpoint.

Agents Window / background agents error out or don't use QCode¶

Some agent sub-capabilities have requirements on the model source and may force the use of Cursor's built-in models rather than a custom endpoint. This is by design on Cursor's side and changes between versions, so defer to Cursor's official docs; you can switch Chat / Composer to QCode while leaving agent flows on Cursor's default.

I don't see the model id I added in the dropdown¶

Confirm that in the Models list you both checked the model and correctly entered its id via + Add model (case-sensitive, no stray spaces). Restart Cursor once after the change to refresh the list.

Next Steps¶

• VS Code Integration — same-family editor with shared configuration patterns
• Endpoints and API Paths — full reference for QCode.cc's three protocols and four ingress domains
• gpt-image-2 Image Generation — dedicated image-generation endpoint
• Subagents — Claude Code subagent usage
• Automation & CI/CD — headless workflows
• Claude Code Tutorial — CLI workflow reference
• Billing — shared quota rules

No API Key yet? Pick a plan at qcode.cc/pricing — one Key works in Cursor, Claude Code, and every tool that supports custom endpoints.