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

Cursor Editor Setup¶

Cursor is an AI-native editor built on top of VS Code. Cursor v3 (released 2026-04) introduces three major new capabilities: Agents Window (multi-agent coordination), Design Mode (visual design synced with code), and CLI agents (sub-agents inside the terminal). This guide shows how to configure QCode.cc as the upstream model source for Cursor — the core is entering a custom Base URL plus your QCode API Key in Cursor settings.

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¶

QCode serves models across three protocols with a single Key. Cursor's custom endpoint is most stable over the OpenAI protocol; just enter the model ids from the table below:

The Gemini family is billed at ×2 on QCode. Full pricing at qcode.cc/pricing.

Configuration Steps¶

Cursor offers two integration paths — pick the one that fits your scenario. Path A (OpenAI protocol) has the best compatibility and is strongly recommended.

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

Use the OpenAI protocol to talk to QCode's /openai/v1 path, giving you access to GPT-5.5 / GPT-5.4 / Gemini and pass-through Claude and other model families.

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).

⚠️ Known limitation: Cursor's support for custom Anthropic endpoints changes between versions, and under Agent mode some capabilities use an OpenAI Responses API style that is incompatible with QCode's Anthropic protocol path in certain scenarios (typically manifesting as failed schema conversion for some tool calls). We recommend Path A over the OpenAI protocol. To use Claude models, add model ids such as claude-opus-4-8 / claude-opus-4-7 under Path A — QCode passes Claude models through transparently at the OpenAI protocol layer. Cursor's endpoint toggles change from time to time, so defer to Cursor's official docs for specifics.

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 over the QCode endpoint; heavily managed features (Tab completion, some agent flows) may stay on Cursor's own models. When Cursor opens up custom endpoints for a given agent feature, defer to their official 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-4-6 for everyday work, claude-opus-4-8 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 4.8 / Sonnet 4.6 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
• Cursor v3 Agents Window has the most stable compatibility with the OpenAI / Anthropic protocols today; support for non-mainstream providers (such as self-hosted OSS models) varies
• The override is a global switch: once you fill in Override OpenAI Base URL, requests that default to the OpenAI protocol inside Cursor get rerouted to QCode. To temporarily revert to Cursor's default, clear that field

Practical Tips¶

• Pick a model per task: claude-sonnet-4-6 gives the best value for everyday editing; reach for claude-opus-4-8 for large refactors / long context; try gpt-5.6-terra for pure code completion
• Prefer the 1M tier for long context: 1M-context models like claude-opus-4-8 / 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¶

Since Cursor v2, Composer defaults to the OpenAI protocol; to select Claude, you must manually add model ids such as claude-opus-4-8 to the Models list (even though QCode passes Claude models through over the OpenAI protocol, Cursor still needs to recognize the model id before it shows up in the dropdown).

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.