Cursor Setup Guide: Pointing It at Your Own Endpoint

Cursor is a VS Code fork with an agent built into it, and the most common misconception about configuring it is that a base URL override redirects the whole product. It does not. Some of what Cursor does happens on Cursor infrastructure regardless of whose key you supply, and understanding that split before you start saves an afternoon of wondering why your usage dashboard is quieter than expected.

The configuration itself is short: a base URL, a key, and at least one model name you have declared. The interesting part is what changes around it.

Cursor is two products sharing a window

One half is the chat and agent surface, where a model reads your files and proposes edits. That half is a fairly normal client of a chat completions endpoint, and it is the half a custom provider can serve.

The other half is the editor intelligence: inline completion as you type, the model that applies a suggested diff to a file, codebase indexing and semantic search. Those are tuned, first-party pieces of Cursor. Historically they have continued to run on Cursor systems even when a custom key is configured, because they are not simply a chat call.

So the honest expectation to set is this: a custom endpoint gives you control over the expensive, high-token reasoning work, not over every model call the editor makes. If your reason for overriding is cost, that is still most of the spend. If your reason is that no data may leave your perimeter, a base URL override alone does not achieve it, and you should be looking at the enterprise privacy controls instead.

Where the provider settings live

Open Cursor settings and look for the models or providers section — the exact label and nesting have moved between releases, so search the settings pane rather than following a click path from memory. What you are looking for is a list of model names with toggles, and beneath or beside it a set of provider credentials with an option to override the API base URL.

Fill in three things. The key goes in the API key field. The base URL override goes in the field that mentions overriding or a custom endpoint, and it should end at the version segment of your provider path, with no operation appended. Then add your model name to the model list, because Cursor will not offer a model it has not been told about.

Most builds put a verify or test button next to the credentials. Use it. It sends a real request, so a green result means the URL, the key and at least one model name agree with each other, which is more than a saved form tells you.

The model name is not negotiable

The string in the model list is passed to your endpoint verbatim. There is no aliasing and no graceful fallback: a name your provider does not publish returns an error rather than quietly substituting something similar.

This is where most setups stall. People enable the override, leave the default model selected in the chat box, and get failures that look like an authentication problem. Add your model name explicitly, then select it in the chat input, and confirm the selector is showing the name you added rather than a built-in default that reverted.

If you are unsure which model to point at for day-to-day work, the model selection walkthrough is a better starting point than a benchmark table, because the thing that matters in an editor is instruction-following and tool discipline rather than raw score.

Verify the override actually took effect

A saved setting is not proof. The reliable check is to compare two sources: ask Cursor a question that costs real tokens, then look at your provider dashboard and confirm a request appeared with the model name you configured and roughly the token count you expected.

If nothing shows up, the request never left for your endpoint. If something shows up but the token counts look tiny compared to the size of the files you attached, you are probably seeing a different feature than the one you tested.

Do this once at setup and again after any Cursor update. Overrides have a habit of surviving updates in the settings file but not in behaviour, and the failure is silent because everything still works — just not through you.

Rules do more for output quality than model choice

Cursor reads project rules from files in the repository, and they apply to every request the agent makes. This is the highest-leverage configuration in the whole product and the one most teams skip.

Put the concrete, checkable things in there: the package manager, the test command, the directories that are generated and must never be hand-edited, the error-handling convention, and an explicit instruction to make the smallest change that satisfies the request and ask before refactoring anything adjacent. Agents over-reach by default and a single sentence about scope pays for itself within a day.

Beyond rules, be deliberate about what you attach to a request. Pulling in half the repository because it is easy is how a cheap session becomes an expensive one, and tighter prompting for coding agents generally beats a bigger context.

What commonly goes wrong

A 401 is usually a key from a different provider, or trailing whitespace from a paste. A 404 on the endpoint is a duplicated version segment in the base URL, since some clients append it themselves. A 404 naming the model is a name your provider does not serve. If all of that is right and requests still fail only in Cursor, a corporate proxy or TLS inspection layer is the next suspect.

The subtler failure is billing surprise in the other direction: you configured an override, assumed everything routes through it, and are paying for both. Check both invoices in the first week. If you are weighing that trade-off, per-token against flat-rate pricing is the comparison to make with your own usage numbers rather than a vendor calculator.

The takeaway

Set the base URL, the key and an explicit model name, verify with the test button, then confirm a real request landed on your provider dashboard. Accept that completion and apply may stay on Cursor infrastructure, and decide whether that is acceptable before you rely on it. If it is not, a tool that is a plain client of your endpoint end to end — Cline among them — gives you a cleaner boundary, and one key across several tools keeps the rotation cost down.