Connect Cursor#
Connect Cursor to OptScale AI so IDE agent chats use your organization's governed model catalog through the OpenAI-compatible gateway endpoint.
In Chat, copy Base URL, API key, and Model name from Get connection values from Chat before you open Cursor settings.
For shared model naming rules and limitations, see External Tools overview.
Prerequisites#
Complete the following before configuring Cursor (same baseline as Connect OpenCode):
- An organization and at least one Active provider exist.
- Allowed providers are assigned for the user connecting Cursor to OptScale AI.
- The cluster exposes a valid TLS certificate (HTTPS is required for the gateway Base URL).
- When using Cursor agents with tools, select a model in Chat that supports tool execution before copying Model name.
Configure Cursor#
1. In Cursor, open File → Preferences → Cursor Settings.
2. Under the Model section, set fields using values from connection values:
| Field | Value from Chat | Example |
|---|---|---|
| Models | Copy the Model name value (comma-separated if you add more; see Model identifiers) | gpt-oss:120b |
| OpenAI API Key | Copy the API key value | 5e0f3a67-84c2-4d0f-ad9d-ec2dc4cecb69 |
| Override OpenAI Base URL | Copy the Base URL value and replace the trailing /v1 with /cursor |
https://localhost:3001/llm_proxy/8f3c2a1b-4d5e-6789-abcd-ef0123456789/cursor |
Note
Cursor uses the /cursor endpoint. If the value copied from Chat ends with /v1, replace only that final path segment before saving Cursor settings.
3. Save the configuration.
Configured models appear in Cursor chats and agent sessions.
Verify the Cursor connection#
- Start a Cursor chat or agent task with one of the added models.
- Confirm the model responds without authentication errors.
- Check Traces in the Admin UI for the corresponding request.
Cursor setup notes#
Note
Cursor supports only one OpenAI-compatible base URL and API key configuration at a time. When OptScale AI is configured as the OpenAI endpoint, models from the original OpenAI connection are no longer available in Cursor.
- Use providers and models allowed for the user.
- Prefer models that support tool execution when using Cursor agents.
Related documentation#
| Topic | Where to read more |
|---|---|
| Connection values from Chat | Get connection values from Chat |
| External tools overview | External Tools |
| Connect OpenCode | Connect OpenCode |
| Initial setup | First Steps |
| AI Access and allowed providers | Core Services — AI Access |
| Request monitoring | Core Services — Traces |
| Chat UI | Interface Overview |