What is Cursor?
Cursor is an AI-first code editor with integrated chat, agent workflows, code editing, and model-powered development features.
Current Cursor documentation does not establish a general custom-provider route. This guide treats TokenHub as conditional: configure it only when your installed client visibly provides a custom Base URL override, then test each feature independently. Cursor does not document a universal third-party provider path for every version, account, and feature. Treat the TokenHub route as conditional on visible API-key and Base URL controls, and test standard Chat, Agent, Apply, and Tab Completion independently because Cursor-specific features may continue to use separate services.
Cursor can route model requests through TokenHub's OpenAI compatible API gateway. Keep the official installation flow, then replace only the API key, Base URL, and model ID.
Use https://us-api.tokenhub.com/v1 as the OpenAI Base URL override. Depending on the Cursor version and selected model, Cursor may use Chat Completions or Responses-style requests, so do not assume a single endpoint path.
When to use it
Start in a small repository or test project. First ask the tool to read files, explain code, or produce a plan; only then enable edits, terminal commands, or agent automation.
Install or open the tool
Follow the official Cursor documentation to install or open the tool. If menus or command names differ, prefer the current official documentation.
For CLI tools, confirm the executable works before adding TokenHub credentials:
# open the tool, then open its model or provider settingsPrepare TokenHub credentials
Create a TokenHub API key and choose a model from the TokenHub model list that fits this tool.
export TOKENHUB_API_KEY="sk-..."Keep the key in your local shell, IDE secret storage, or the secure API key field of the tool. Do not commit it to the repository.
Configure TokenHub persistently
Use the tool configuration file or settings page first. This avoids the common problem where a terminal sees the environment variable but the IDE, plugin, or new window does not.
Provider values
Cursor officially supports BYOK for specific providers and standard chat models. A custom OpenAI-compatible endpoint is currently a limited Base URL override, not a first-class custom provider.
| Field | Value |
|---|---|
| Settings | Cursor Settings → Models → API Keys |
| API key field | OpenAI API Key |
| Base URL option | Override OpenAI Base URL |
| Base URL | https://us-api.tokenhub.com/v1 |
| Model | A TokenHub model compatible with the request format Cursor sends |
Settings file locations
| Field | Value |
|---|---|
| macOS | ~/Library/Application Support/Cursor/User/settings.json |
| Windows | %APPDATA%\Cursor\User\settings.json |
| Linux | ~/.config/Cursor/User/settings.json |
Use the settings UI first when the extension owns the schema. It stores the same values in a user-level settings file and avoids guessing private keys that may change between releases.
Custom keys apply only to standard chat models. Tab Completion and Cursor-owned models continue through Cursor. Some current Cursor versions can also send a Responses-shaped body to a Chat Completions path through the override, so verify a read-only chat before relying on Agent mode. If the Base URL override is absent or the request format is rejected, that Cursor version cannot connect to TokenHub reliably.
Do not map Chat, Agent, Composer, Apply, Fast, or Tab as if they were equivalent custom-provider slots. Start with one standard chat model and treat every other feature as unsupported until its requests appear successfully in TokenHub logs.
Temporary environment variables for debugging
Use the settings UI first when the extension owns the schema. It stores the same values in a user-level settings file and avoids guessing private keys that may change between releases.
Use temporary variables only to confirm the key, network, and model name. After validation, move the same values into the persistent configuration above.
Verify the connection
Test with a read-only prompt first, confirming that the model can read context without changing files. Then test edits, Apply, or agent tasks.
Read the project README and summarize it in three sentences. Do not modify any files.After a successful prompt, check TokenHub request logs for model name, endpoint, token usage, and billing group.
Troubleshooting
| Symptom | Fix |
|---|---|
| 401 or authentication failure | Confirm TOKENHUB_API_KEY is valid and saved in the same terminal, IDE, or client profile. |
| 404 or model not found | Use a model ID that exists in your TokenHub workspace and matches the selected protocol. |
| Wrong endpoint | Keep the Base URL exactly as shown. OpenAI-compatible tools usually need /v1; Claude-compatible tools usually do not. |
| Request timeout | Check network access to https://us-api.tokenhub.com, proxy settings, and workspace allowlists. |
| Tool uses another model | Recheck every chat, edit, apply, fast, and autocomplete model slot. |
Choose a compatible Cursor model
Cursor custom API compatibility FAQ
Why is there no Override OpenAI Base URL setting in Cursor?
The setting varies by Cursor version and account. Without visible override controls, this page does not establish a direct TokenHub configuration route.
Why can Tab Completion still use Cursor after I configure TokenHub?
A custom API key or Base URL override does not necessarily apply to Tab Completion and other Cursor-specific capabilities.
Does a successful chat mean Cursor Agent is compatible too?
No. Cursor features can use different request formats and model paths. Test chat, edits, and Agent separately and review TokenHub request logs.
How do I troubleshoot a Cursor custom-model 404?
Check that the Base URL ends in /v1 and the model ID is accepted by the current UI. If TokenHub receives no request, that Cursor feature may not use the override.
Which Cursor features should I test separately?
Test standard Chat, Agent, Apply, and Tab Completion independently. A custom provider setting may affect only some request paths.
References
This setup is based on TokenHub and official documentation, last verified on 2026-09-04.
