Use a Claude API Key in Cursor: Custom Endpoint Setup, Model Names, and the Errors
Cursor lets you override the OpenAI base URL, which means you can drive it with any OpenAI-compatible endpoint. Two minutes to configure, and nearly every failure lands in one of three places.
Why this works at all
Cursor speaks the OpenAI chat completions protocol. Any endpoint implementing that protocol is a valid target, which is why the base URL is exposed as a setting rather than hidden. Nothing is being worked around — this is the intended extension point, and the same trick works for any OpenAI-compatible tool.
The two-minute setup
Open Settings → Models. Enable the custom OpenAI key option, paste your key, and set the base URL to your provider's endpoint — for cocodot that is `https://cocodot.co/api/ai/v1`, including the `/v1`. Add the model names you intend to use. Then verify with a Chat message before touching anything else; if Chat works, the connection is correct and any remaining issue is mode-specific rather than configuration.
Model names are the first source of errors
A `model not found` response means the endpoint does not serve that name — not that your key is wrong. With cocodot both forms work: the official names (`claude-sonnet-5`, `claude-opus-5`) and the gateway codes (`mcs-6`, `mco-7`). The full list is published at cocodot.co/pricing#models, and the machine-readable version is `GET https://cocodot.co/api/ai/models` if you would rather copy from JSON than a page.
The modes behave differently — expect that
Chat works fully through a custom endpoint. Tab completion uses Cursor's own models regardless of your setting, so do not expect your endpoint to change it. Agent and Composer lean on tool-calling behaviour and are sensitive to how faithfully a model implements it; test them separately after Chat is confirmed. Knowing this in advance saves you from concluding the whole setup is broken when only one mode is.
A cost split that actually holds up
Use a mid-tier model as the default for reading code and making scoped edits, and switch to a frontier model only for genuinely hard problems. On published rates that is roughly a fifth of the cost for the majority of your calls, and in day-to-day coding the difference is much smaller than the price gap suggests. Since both run on the same key and balance here, switching is a dropdown rather than a migration.
Verifying before you rely on it
1. Send a Chat message and confirm a reply. 2. Check the call appears in your provider's billing detail — that confirms the request actually routed through your endpoint rather than falling back. 3. Try Agent on a small task. 4. Confirm your balance moves by the amount you expect. If step 2 shows nothing, Cursor is not using your endpoint, and the base URL is the first thing to re-read.
Cursor has two different key slots — do not mix them
Cursor separates the OpenAI key field (with the overridable base URL) from the Anthropic key field. If you want to use a Claude model through an OpenAI-compatible gateway, the key goes into the OpenAI slot together with the gateway's base URL, and you select the model by the name the gateway serves. Pasting a gateway key into the Anthropic slot sends it to Anthropic's own address, where it fails with an authentication error that looks like a bad key but is really a wrong destination. Which slot is which can shift between Cursor versions, so if a screen does not match this page, check Cursor's current docs for the field names.
Where the request actually comes from
Per Cursor's documentation at the time of writing, requests made with a custom key are sent from Cursor's servers, not directly from your machine. Two consequences follow. An endpoint running only on your own laptop (localhost) will not be reachable, so a public HTTPS endpoint is required. And the provider sees Cursor's server address rather than yours, so an IP allowlist on your key will block everything. If a request never shows up in your provider's billing detail, this is a likely reason; verify against the current docs, since architecture like this can change.
Reading the errors
401 or 'invalid API key' — the key is wrong, expired, or in the wrong slot. 404 or 'not found' on the URL — the base URL is missing `/v1` or has an extra path segment. 'Model not found' or 400 — the endpoint does not serve that model name; copy the exact string from the provider's model list rather than typing it from memory. 402 or 'insufficient balance' — the key is valid but has no credit, and retrying will not help. 429 — you hit a rate limit and should back off; see our guide to 429 errors for the three limit types. A timeout on Agent only — usually a long tool-calling turn, not a connection fault. Match the message to this list before changing any setting.
What custom keys do and do not replace
A custom endpoint changes where Chat-style requests go. It does not replace features Cursor implements on its own infrastructure, and which features fall in which group depends on your Cursor version and plan. The honest test is empirical: enable the custom key, then run one request in each mode you rely on and compare what appears in the provider's billing detail. If a mode does not appear there, Cursor handled it itself. Doing this once takes five minutes and prevents weeks of assuming a feature runs on your key when it does not.
What to put where
| Field | Value | Common mistake |
|---|---|---|
| API key | Your key from the provider console | Using an expired or zero-balance key |
| Base URL | https://cocodot.co/api/ai/v1 | Omitting the trailing /v1 |
| Model name | claude-sonnet-5, or the gateway code mcs-6 | A name the endpoint does not serve |
| Verify step | Run Cursor's key check, then send one Chat message | Treating a green check as proof — only a real reply is proof |