Cursor

Point Cursor's bring-your-own-key lane at the gateway: every model your org holds a key for, in Ask, Plan, and Agent, with the full optimizer and per-developer spend.

Cursor exposes a custom base URL for chat models only, so chat is the whole supported surface. Tab autocomplete, inline edit (Cmd/Ctrl+K), Cloud Agents, and Cursor's own models (Auto, Composer) stay on Cursor and never reach the gateway.

Before you start you need a gateway on public HTTPS, because Cursor's servers make the call. You also need one provider key on the gateway, Cursor Pro, Teams, or Enterprise, and each developer enrolled with a personal ark_… key.

Route Cursor through Anyray

1

Quit Cursor

The write only lands while Cursor is closed.

2

Connect the developer

Direct gateway

Direct gateway

anyray-connect https://gateway.example.com --org --tools cursor \
  --user developer@example.com --yes

Anyray SSO

Anyray SSO

anyray-connect --sso https://app.anyray.ai/sso/<tenantId> --org --tools cursor --yes

--org selects this route. It sets Cursor's Override OpenAI Base URL and OpenAI API Key, and installs the hooks and MCP server.

3

Add the model in Cursor

Cursor → Settings → Models → add a custom model named anyray-default and enable it. Leave every other provider-key field (Anthropic, Google, Azure, Bedrock) off.

4

Pick it in the chat box

Choose anyray-default in Ask, Plan, or Agent. It routes to your deployment's default model.

Pick only names you added. While the override is on, Cursor sends every OpenAI-family model through it, built-in entries such as gpt-5.5 included, and those fail.

5

Verify the lane

anyray-connect doctor --verify

This passes only when the base URL, the enable toggle, the personal ark_… key, and at least one registered custom model all match. Then send one Ask prompt and find it in console Traces. Finish with one Agent turn that edits a file, which proves the tool-call round trip on your build.

A routed request gets the same treatment as Claude Code: prompt caching that stabilizes the tools, system, and settled prefix (cache_optimizer), the deterministic strategies, per-developer per-model spend, and the local hooks. Claude and Gemini ride the same OpenAI-compatible lane, because the gateway translates each request into the provider's native wire format, tool calls included.

Offer a menu of models

Cursor rejects a custom model whose name matches a built-in, so each alias gets an Anyray name:

PUT /admin/model-aliases

{
  "anyray-opus": "anthropic/claude-opus-5",
  "anyray-sonnet": "anthropic/claude-sonnet-5",
  "anyray-gpt": "openai/gpt-5.5"
}

An alias binds a provider and a model, so it routes correctly even with several provider keys on the gateway. Re-pointing one later switches every developer with no client edit. Add those names as custom models in Cursor. The endpoint is admin-gated (modelaliases:write), and ANYRAY_MODEL_ALIASES seeds the same map at boot (endpoint reference).

Set it up by hand

Cursor publishes no managed-config format for these settings, so Connect updates only the two cells it recognizes and prints these steps on an unfamiliar shape.

1

Open the key settings

Cursor → Settings → Models → OpenAI API Key.

2

Override the base URL

Enable Override OpenAI Base URL and set it to https://gateway.example.com/v1/seat/cursor.

3

Set the key

Paste the personal key from anyray-connect print-key, then restart Cursor and add the models as above.

What it costs, and who sees the prompt

Provider usage bills to the org's key at list price, less what the optimizer removes. The lane counts as one Anyray subscription seat per active developer, identified by the /v1/seat/cursor path because Cursor cannot send a seat header (endpoint reference).

Cursor still charges its seat. On Teams and Enterprise its Token Rate (US$0.25 per million tokens) applies to BYOK requests on third-party models too.

Cursor's servers still see the prompt. Every BYOK request is assembled on Cursor's backend before it reaches the gateway, and Cursor's Zero Data Retention terms do not cover BYOK. What the gateway keeps is set by Anyray's content mode, encrypted by default.

Retrieval-gated trimming depends on Cursor exposing the tool

The in-flight eliders (relevance_filter and friends) run when the request itself declares the anyray_retrieve tool. A fresh authenticated lease covers later requests whose tool catalog is deferred. Connect renews the lease every 5 minutes while Cursor keeps the initialized stdio transport alive, and it expires after 6 hours without verified activity.

Whether Cursor forwards an installed MCP tool into its BYOK request varies by release, and everything above applies regardless. A routed Agent trace shows either the eliders among the optimizer decisions or a no_retrieve reason.

Troubleshooting

Symptom	Cause and fix
The model "X" is already available as "Y" when adding a model	The name collides with a Cursor built-in. Register an alias and add that name.
Traces stays empty and doctor reports no model registered on the lane	Step 3 never ran, so the lane carries nothing. Add anyray-default or an alias, enable it, relaunch, then select it.
Traces stays empty and doctor reports the lane healthy	The selected model is one of Cursor's own. Auto, Composer, and the native Claude entries never leave Cursor. Pick an Anyray name.
424 with no provider key configured for <provider>	The alias points at a provider with no key on the Providers page. Add one or re-point the alias.
The Agent explains a change but never edits the file	Another provider key is enabled alongside the override, so requests leave in a shape the lane cannot serve. Disable it, quit Cursor fully, relaunch.
A request with no model lands on the gateway (a Cursor 3.x Agent-mode bug)	The lane fills it with anyray-default, so it routes to the org default. Register an alias to put that turn on a different model.
doctor reports Cursor not pointed at the gateway after it worked	Cursor rewrote its settings store. Quit Cursor, run anyray-connect doctor --repair, relaunch.
A built-in model errors with The requested model is not available	The override captured a Cursor-managed OpenAI-family model. Pick an Anyray name instead.

Keep Cursor's native models

For an org staying on Cursor's own Claude and Opus entitlement. Anyray cannot see the model request, but it still reduces the local tool context that feeds it.

1

Enroll the developer without --org

Direct gateway

Direct gateway

anyray-connect https://gateway.example.com --tools cursor \
  --user developer@example.com --yes

Anyray SSO

Anyray SSO

anyray-connect --sso https://app.anyray.ai/sso/<tenantId> --tools cursor --yes

This adds no inference base URL and copies no Cursor credential.

2

Restart Cursor once

Cursor loads the MCP registration on launch. hooks.json reloads on its own.

Coming from the BYOK route? Connect first restores the two journaled Cursor settings, which needs Cursor fully closed. When it reports the restore as queued, quit Cursor, wait for the watcher, then reopen.

3

Verify native mode

anyray-connect status

Healthy means the owned Shell, Read/Grep, MCP, and prompt hooks plus the retrieval MCP registration are all present. A normal prompt on a native Claude or Opus model should not appear as a gateway inference trace. A savings event shows in Traces as a connect hook · tool-output optimization entry.

The setup installs four seams:

Seam	What it does
preToolUse shell hook	Runs recognized bulky shell commands through Anyray's output reducer.
preToolUse Read/Grep hook	Redirects a bulky built-in Read or Grep to anyray_read or anyray_search, so content arrives trimmed on the re-issue.
postToolUse MCP hook	Replaces an oversized MCP result before the model consumes it.
The anyray MCP server	anyray_retrieve, anyray_recall, anyray_search, anyray_read, anyray_history. This is how native Cursor gets gateway optimization on content it would otherwise gather with an unoptimizable built-in tool.

Size gates and fail-open limits: Cursor reference.

Routing boundary

The OpenAI override is the only Cursor inference seam that points at another base URL. Native Team Claude and Opus, Tab, inline edit, Cloud Agents, indexing, and other first-party traffic cannot be redirected, so hook savings are this setup's optimization boundary.

For full request-level optimization of a subscription-backed Claude or Opus session, use Claude Code with a separate Claude Pro, Max, Team, or Enterprise entitlement. It supports subscription OAuth through an ANTHROPIC_BASE_URL gateway, and a Cursor Team entitlement cannot be used by Claude Code.

What Cursor's Admin API can and cannot import: Cursor reference.