Skip to main content

Cursor IDE

Cursor IDE has native support for a custom OpenAI-compatible endpoint. Point it at an LLM Registry entry through the gateway's Cursor-compatibility path, and Cursor can use any provider the entry serves, including Gemini and Bedrock, not just OpenAI-family models.

All configuration lives in Cursor's Settings under Models. You'll do this in the UI, and there are no CLI commands to run.

Which setup do you need?​

What you getUse it when
LLM Registry entryThe model, governedYou only need model access
Agent PersonaThe model and the persona's MCP toolsYou want Cursor to use tools as well

Connect to an LLM Registry entry​

1. Enable "Override OpenAI Base URL"​

In Cursor Settings → Models → API Keys:

  • Toggle Override OpenAI Base URL on
  • Paste the entry's URL, including the required /api/v1/cursor suffix:
https://<gateway-host>/llm/<url-prefix>/api/v1/cursor

2. Set the OpenAI API Key​

Cursor has exactly one credential field, so what goes in it depends on your entry's credential mode. Cursor sends this value as Authorization: Bearer on every request.

Your entryPaste into OpenAI API Key
API Key, or AWS SigV4<your-agent-access-key>
Passthrough, Require an agent access key on<your-provider-key>::<your-agent-access-key>
Passthrough, requirement off<your-provider-key>

The middle row is the combined form: two credentials in one field, provider key first, separated by two colons. The gateway splits the value apart before authenticating. Provider key first matters, because Cursor checks that a key looks well-formed and only this order passes that check. See clients with only one credential field for the full explanation.

Not sure which row applies? Which credentials does my entry need? settles it.

3. Enable the models you want to use​

Below API Keys, Cursor lists its default OpenAI models. Toggle those off if you want to use custom-provider models exclusively, then use the Add or search model input to add each model ID from the entry's Allowed Models list. Enable the toggle next to each.

The identifier format depends on the provider:

Add model IDs as they appear in the Allowed Models list. In passthrough mode, <your-provider-key> is your OpenAI API key.

note

Some OpenAI models return errors from Cursor when routed through the compatibility path. If a model fails, try a different one from the Allowed Models list. The issue is model-specific, not endpoint-wide.

Connect through an Agent Persona​

An Agent Persona bundles a set of MCP tools and, optionally, LLM access under one endpoint. Cursor reaches both, through two separate settings.

1. Point the model at the persona​

Same Override OpenAI Base URL field as above, with the persona-scoped URL:

https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>/api/v1/cursor

The /api/v1/cursor suffix is still required. Fill the OpenAI API Key field exactly as in step 2 above, and add models the same way.

2. Wire the persona's tools​

Add the persona's tools socket to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "<persona-name>": {
      "url": "https://<gateway-host>/p/<persona-id>",
      "headers": { "X-Agent-Key": "<your-agent-access-key>" }
    }
  }
}

One Agent Access Key covers both. The same key authenticates the model route and the tools socket, whichever Inbound Authentication method the persona uses.

note

This route always requires an Agent Access Key, whatever the entry's credential mode. Fill the credential field using the API Key or Passthrough (Agent Access Key Required) guidance above; the third mode, Passthrough (No Agent Access Key), applies to the LLM Registry entry route only.

note

The tools socket URL is the persona root, with no /llm/... path and no /api/v1/cursor suffix. The model route and the tools socket are different endpoints on the same persona.

If you'd rather not edit the file by hand:

npx @cequenceai/mcp-cli@latest cursor \
  --url "https://<gateway-host>/p/<persona-id>" \
  --name "<persona-name>" \
  --header 'X-Agent-Key: <your-agent-access-key>'

Where to find each value​

PlaceholderWhere to find it
<gateway-host>Host from the entry's Overview tab
<url-prefix>The URL prefix field on the entry's Overview tab
<persona-id>The persona's ID on the Agent Persona page
<persona-name>Any short name you want Cursor to use for this MCP server locally
<registry-entry-id>The LLM Registry entry's ID in the entry's URL
<your-agent-access-key>Generate from the entry's Agent Access Keys step, or the persona's Connect flow. Plaintext is shown once.
<your-provider-key>Your own provider API key, needed only in the passthrough modes
Model IDsThe entry's Allowed Models list

Tips​

  • The /api/v1/cursor suffix is required on the model URL. It's what tells the gateway to apply the Cursor-compatibility translation. Without it, Cursor's requests reach the gateway but the response shape may not match what Cursor expects.
  • Only the Override OpenAI Base URL field is used. Even for Anthropic or Gemini entries, keep the toggle for Override Anthropic Base URL / Override Google API Base URL off. Cursor routes everything through its OpenAI adapter when the OpenAI override is on, and the gateway's Cursor path handles the translation on its side.
  • Test a single model first. Add one model from the Allowed Models list, enable it, and try a chat before adding the rest. That way if the base URL or key is wrong, you catch it before spending time enabling ten models.
  • Custom model IDs stay case-sensitive. Cursor stores the exact string you type, and the gateway forwards it verbatim. Match the entry's Allowed Models list exactly.
  • Two colons, no spaces. In the combined credential, :: is the separator. A space on either side becomes part of the credential and authentication fails.
  • An "invalid API key" error may be about the wrong key. On a passthrough entry that requires an Agent Access Key, sending only your provider key fails authentication even though that key is perfectly good. Check which credentials your entry needs before regenerating anything.
Last updated on