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 → click View All Models.

   

3. Click +Add Custom Model.

   

4. Enter the model name:

   • In OptScale AI Chat, select the provider and model you want to connect. Then go to Connect this model to external tools → CURSOR and copy the Model name value.

     

   • In Cursor, paste the copied value into the Enter model name field, then click Add.

     

5. Enter the API key and Base URL:

   • In Cursor, expand the API Keys section.

     

   • In the Connect this model to external tools → CURSOR dialog in OptScale AI Chat, copy the API key value.

     

   • In Cursor, paste the copied value into the OpenAI API Key field.

     

   • In Cursor, enable Override OpenAI Base URL.

   • In the same Connect this model to external tools → CURSOR dialog in OptScale AI Chat, copy the Base URL value.

     

   • In Cursor, replace the existing value in the Override OpenAI Base URL field with the copied value.

     

6. Save the configuration.

Configured models become available in Cursor chats and agent sessions.

Verify the Cursor connection#

1. Start a Cursor chat or agent task and select one of the added models.
2. Confirm the model responds without authentication errors.
3. Check Analytics → Traces in the OptScale AI Admin UI for the corresponding request.

Cursor setup notes#

• Use providers and models allowed for the user.
• Prefer models that support tool execution when using Cursor agents.

See also#

• Get connection values from Chat — Shared Base URL, API key, and model values.
• External Tools — Overview and shared limitations.
• Connect OpenCode — Route OpenCode agent chats through the gateway.
• Core Services — Traces — Verify requests after connecting.