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

Ensure the following prerequisites are met before configuring Cursor:

• An organization exists and at least one Active provider is configured.
• 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 models that support tool execution before copying Model name.

Configure Cursor

1. Open the Cursor Settings page:

   • For Windows and Linux: File → Preferences → Cursor Settings
   • For macOS: Cursor → Settings → Cursor Settings

2. Go to Models → View All Models → + Add Custom Model.

3. Enter the model name: OptScale AI Chat → Connect this model to external tools → CURSOR → copy the Model name value.

4. In the API Keys section:

   • Enable OpenAI API Key and confirm the action.

   • Enter the API key: OptScale AI Chat → Connect this model to external tools → CURSOR → copy the API key value.

   • Enable Override OpenAI Base URL.

   • Enter the base URL: OptScale AI Chat → Connect this model to external tools → CURSOR → copy the Base URL value.

5. Save the configuration.

Configured models appear in Cursor chats and agent sessions.

Verify the Cursor connection

1. Start a Cursor chat or agent task with one of the added models.
2. Confirm the model responds without authentication errors.
3. Check Traces in the OptScale AI 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

After connecting Cursor, you may want to:

• Review shared connection values in Get connection values from Chat.
• Read the broader External Tools overview.
• Configure another client with Connect OpenCode or Connect Claude.
• Check setup requirements in First Steps.
• Manage user access in Core Services — AI Access.
• Monitor requests in Core Services — Traces.
• Review Chat controls in Interface Overview.