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.

What works in Cursor

Cursor surface	Through Anyray?	What you do
Chat (Ask, Plan, Agent; edits and tool calls included)	Yes	Pick an Anyray model in the chat box
Tab autocomplete	No	Nothing; stays on Cursor's own model
Inline edit (Cmd/Ctrl+K)	No	Nothing; stays on Cursor
Cloud / Background Agents	No	Cursor does not support custom keys here
Cursor's own models (Auto, Composer)	No	Never leave Cursor

Chat is the whole supported surface, because Cursor exposes a custom base URL for chat models only. To stay on Cursor's own Claude and Opus entitlement, skip to Keep Cursor's native models.

Route Cursor through Anyray

Cursor lets you override the base URL of its OpenAI provider slot. Point it at the gateway, and every chat request for the models you register goes through Anyray on the org's server-held key.

Claude and Gemini ride the same OpenAI-compatible lane. The gateway translates each request into the provider's native wire format, tool calls included.

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 plus the anyray_retrieve MCP server that --tools cursor installs.

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.

1

Connect the developer

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

With SSO enrollment: 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. Quit Cursor fully first, because the write only lands while Cursor is closed.

2

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.

3

Use it

Pick anyray-default in Ask, Plan, or Agent. It routes to your deployment's default model and shows per developer in console Traces.

Pick only the names you added

While the override is on, Cursor routes every OpenAI-family model through it, built-in picker entries such as gpt-5.5 included. A Cursor build with an Anthropic key also enabled sends Claude through it in a shape no OpenAI endpoint accepts. Select the Anyray names, and leave Cursor's built-in entries alone.

Offer a menu of models

For a menu beyond anyray-default, an admin registers aliases. Cursor rejects a custom model whose name matches a built-in, so each one 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, alongside or instead of anyray-default. The endpoint is admin-gated (modelaliases:write), and ANYRAY_MODEL_ALIASES seeds the same map at boot (endpoint reference).

Verify the lane

anyray-connect doctor --verify passes only when the base URL, the enable toggle, and the personal ark_… key all match, and at least one custom model is registered on the lane. Then send one Ask prompt on an Anyray model 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.

Manual setup

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.

Costs and privacy

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 2 never ran, so the lane carries nothing. Add anyray-default or an alias under Cursor → Settings → Models, 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. Enroll the developer, then run the same command 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. It 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.

Restart Cursor once after setup so it loads the MCP registration. hooks.json reloads on its own. If a previous run installed the BYOK route, Connect restores the two journaled Cursor settings first, which needs Cursor fully closed. When Connect reports the restore as queued, quit Cursor, wait for the watcher, then reopen.

Verify native mode

anyray-connect status is healthy only when the owned Shell, Read/Grep, MCP, and prompt hooks plus the retrieval MCP registration are present. The probe checks the personal key through GET /connect/savings. 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.

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.