Cursor Integration
Applicable role: Developer Updated: 2026-07-15
Cursor is an AI-native IDE with built-in features such as AI chat, code generation, and Agent mode. By configuring the Override OpenAI Base URL, you can route Cursor's AI features through the platform API to call models.
Prerequisites
- Cursor is installed (download from cursor.com)
- A Cursor Pro or higher subscription (the free tier does not support custom Base URLs)
- An API Key has been created in the platform console
- The Base URL has been confirmed
Configuration Steps
Step 1: Open the Settings Page
Press Cmd + , (macOS) or Ctrl + , (Windows/Linux) to open Cursor Settings, then click the Models tab on the left.
Step 2: Disable Built-in Models with the Same Name
In the model list on the Models page, turn off the switches for the built-in models you plan to replace with the platform (the switch on the left turns gray).
If you don't disable them, Cursor may still use the built-in model channel, causing requests to bypass your configured Base URL and continue consuming your subscription quota.
Step 3: Add a Custom Model
Find the option to add a model on the Models page and manually enter the name of the model you want to use. The model name must match the one on the platform's "Usage Guide" page, for example:
claude-sonnet-4-6gpt-4oclaude-opus-4-7
Step 4: Fill in the API Key and Base URL
Find the following two fields on the Models settings page:
| Field | What to Enter | Example |
|---|---|---|
| OpenAI API Key | The platform's API Key | sk-xxxxxxxx |
| Override OpenAI Base URL | The platform's API address | YOUR_API_BASE_URL/v1 |
The Base URL must end with
/v1. Cursor automatically appends/chat/completionsto it. If you omit/v1, you will get a 404 error.
Step 5: Verify the Connection
Click the Verify button to test the connection.
Note: If the model name you entered is not an official OpenAI name (such as claude-sonnet-4-6), Verify may report a warning, but this does not affect actual usage.
Workaround: First temporarily add a gpt-4 to pass Verify (confirming that the Base URL and Key are connected), then add the actual model name you want to use.
After verification succeeds, open Cursor's Chat or Composer panel, select the model you just added, and send a test message to confirm it responds normally.
Important Notes
Scope of the Custom API
Cursor's Override OpenAI Base URL only affects the Chat and Plan panels. The following features still go through Cursor's official backend and cannot be handled by a third-party API:
- Tab autocomplete
- Inline Edit
- Apply (applying code)
- Some of Composer's Agent features
If you only want to use platform models in Chat, this limitation does not affect you.
Model Names Must Be Exact
When Cursor sends a request, it uses the value of the model field you entered in Settings. If you enter the wrong model name, the call will fail. We recommend copying the exact model name from the "Usage Guide" page in the platform console.
FAQ
Q: Can I use a custom Base URL on the free tier? A: No. The Override OpenAI Base URL is a feature available to Cursor Pro subscriptions and above.
Q: What should I do if Verify reports an error?
A: Common causes: 1) The Base URL is missing /v1 at the end; 2) The API Key is incorrect; 3) The model name is not an official OpenAI name (warnings for non-OpenAI names can be ignored and do not affect actual usage).
Q: My Cursor subscription quota is still being consumed after configuration? A: Check whether you have disabled the built-in models with the same name. If the switches for the built-in Claude/GPT models are still on, Cursor may prioritize the built-in channel over your custom Base URL.
Q: Why doesn't Tab autocomplete go through my API? A: Features like Tab autocomplete and Inline Edit are locked to Cursor's official backend. Only the Chat / Plan panels support a custom Base URL.
Q: What should I do if I get a "model not found" error when switching models?
A: Confirm that the model name matches what the platform actually provides. Different platforms may name the same model differently (e.g., claude-3-5-sonnet vs claude-3.5-sonnet). Copying the call name from the console is the most reliable approach.