Cursor

Keep Cursor Team's native Claude and Opus models. Anyray can reduce supported local tool context, but Cursor does not expose the native model request to the gateway.

Choose the Cursor mode

Mode	Model credential	What Anyray can optimize	Gateway inference trace
Cursor Team Claude/Opus	Cursor Team sign-in; no provider API key	Supported local Shell and MCP results through Cursor hooks	No. Native inference stays on Cursor.
OpenAI BYOK override	A server-held provider API key behind Anyray	Eligible custom-model requests Cursor sends to the endpoint, plus local hook surfaces	Yes, for the routed BYOK request.

Native Team mode is the Cursor default because Anyray's supported Cursor customers use Team entitlements. The BYOK route is a separate API-billed path, requires explicit --org, and cannot spend the Cursor Team entitlement.

Keep Cursor Team Claude or Opus

Enroll the developer with a personal Anyray ark_… key, then run:

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

For Anyray SSO enrollment, use the tenant link instead; the IdP identity supplies attribution and the link supplies the gateway, so no --user, --gateway, or --subscription flag is needed:

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

Cursor's own SAML/OIDC login is independent and remains inside Cursor. Whether the Team user signs into Cursor with SSO or a password does not change this route. Anyray SSO only mints the personal ark_… key used by hooks/MCP; it is not a provider credential.

This command does not add an Anthropic key, copy a Cursor credential, or install an inference base URL. It keeps Cursor's Team sign-in and native model selection, then installs:

• A user-level preToolUse hook for recognized, simple Shell commands with bulky output — test and search runs, plus read-only diagnostics like git log/git diff, container and cluster logs (docker logs, kubectl get), system logs, and build output. On macOS and Linux, the hook runs the command through Anyray's output reducer while preserving its exit code. The wrapper invokes the parsed executable directly and buffers up to 16 MiB before reducing it, so a matching command that depends on a shell alias/function can behave differently and live output can be delayed. Streaming forms (docker logs -f, tsc --watch), complex shell commands, and anything on Windows fail open and run normally.
• A user-level preToolUse hook that redirects a bulky built-in Read or Grep to the Anyray equivalent. Cursor cannot rewrite a built-in tool's output, so the hook declines the call once and tells the agent to call anyray_read / anyray_search instead — the agent re-issues it and the content arrives trimmed. It is deliberately narrow: only files of 16 KiB or more, only targets inside the workspace, and at most one redirect per file or search per conversation, so a retry always gets through. Everything else — small reads, files outside the workspace, non-text files — runs normally.
• A user-level postToolUse hook for MCP results. Cursor's updated_mcp_tool_output field lets Anyray replace an oversized object-valued MCP result before the model consumes it.
• The anyray MCP server, which (a) lets the local Agent recover context externalized behind an Anyray handle (anyray_retrieve / anyray_recall), and (b) exposes anyray_search and anyray_read. Because a native tool's output cannot be optimized in-flight, routing bulk work through these Anyray tools is how native Cursor gets gateway optimization on content it would otherwise gather with an unoptimizable built-in tool. anyray_search returns workspace matches that ride the postToolUse hook to the gateway, where relevance_filter ranks and trims them to the query (semantically on that path). anyray_read returns a file the same way, but the trim is reversible — the gateway leaves a retrieve ctx_… handle, so a file you explicitly asked for comes back as the relevant slice with any elided lines recoverable via anyray_retrieve.

The hook keeps no local content cache or tee for Cursor. Gateway request logs and savings/spend rows remain metadata-only; any trace decision content follows the deployment's ANYRAY_CONTENT_MODE (encrypted by default, while off stores none). The prompt hook can record a content-free oversized-paste opportunity, but Cursor does not let it rewrite the submitted prompt.

Native inference is still outside the gateway

Cursor publishes an OpenAI BYOK base-URL override, but no Anthropic or native-model endpoint override. It also does not provide its Team model credential to custom endpoints. Claude/Opus requests therefore stay on Cursor's service and do not produce Anyray inference traces. Shell/MCP hook savings are the supported optimization boundary.

If a previous Connect run installed the OpenAI BYOK route, native mode restores the two journaled Cursor settings first. Cursor must be fully closed for that database restore. When Connect reports the restore as queued, quit Cursor, wait for the watcher to finish, and reopen it. Restart once after setup so Cursor loads the MCP registration; hooks.json itself reloads automatically.

Cursor cloud agents do not load user-level ~/.cursor/hooks.json. Project hooks can run in cloud agents, but Cursor currently defers its MCP before/after hooks there, and a cloud VM does not have the developer's local Anyray binary or key. This setup covers local Cursor Agent work.

Make it seamless for the team

The anyray_search / anyray_read tools only optimize when the agent chooses them, and Cursor owns tool selection. The preToolUse redirect above already covers the case that costs the most — a bulky built-in Read or Grep — without anyone naming a tool. A rule covers the rest, so the agent reaches for them first instead of being turned back:

• Per repository (automatic): run anyray-connect --tools cursor from anywhere inside a git checkout and it writes .cursor/rules/anyray.mdc at the repo root with alwaysApply: true. Commit the file — that is what shares the steer with everyone who clones the repo.
• Team plan (recommended, org-wide): in Cursor's dashboard, add a Team Rule with the text below and mark it Required. It applies to every member in every repo automatically — the one org-wide, always-in-context steer, and the closest match to how the base-URL integrations "just work."

Prefer the anyray_search and anyray_read tools over the built-in codebase search and file read. anyray_search returns relevance-filtered matches; anyray_read returns the pertinent slice of a file plus a retrieve handle you can pass to anyray_retrieve to recover any elided detail. Use them when finding or reading code.

The repo file is safe to re-run: identical content is left untouched, drift is refreshed, and an anyray.mdc you wrote yourself is never overwritten — Connect warns and leaves it alone. Running outside a git repo is a silent no-op, and a failed write never fails Cursor setup.

anyray-connect also prints this rule after Cursor setup so you can paste it into the dashboard. A rule is steering, not enforcement — Cursor makes the final tool choice — but a Required team rule keeps it in context on every turn, which saves the redirect round-trip. The postToolUse / preToolUse hooks (shell trims, MCP-output trims, and the bulky Read/Grep redirect) run automatically regardless, so a user who never sees the rule is still covered on the bulky path.

Verify native mode

Run anyray-connect status or anyray-connect doctor --verify. Native mode is healthy only when the owned Shell, Read/Grep, MCP, and prompt hooks plus the retrieval MCP registration are present. The verify probe checks the personal key through content-free GET /connect/savings; it does not fabricate an Anthropic request or require a provider key.

Select a native Claude or Opus model in Cursor. A normal prompt should not appear as a gateway inference trace. A savings event appears only after Anyray actually reduces a supported oversized Shell or MCP result. Each such optimization does show in the console Traces view as a connect hook · tool-output optimization entry — labeled with the tool and user and the tokens saved — so you get per-user activity there even though the model call itself stays Cursor-hosted.

Cursor documents the relevant contracts in Hooks, third-party hooks, Cloud agents, and Bring your own API key.

Optional: route the OpenAI BYOK lane

Use this only when the organization intentionally supplies an upstream API credential:

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

Connect writes two exact values in Cursor's settings store: the OpenAI base URL and the personal Anyray key. It backs up only those values, and --revert restores them without touching unrelated Cursor state. If Cursor is open, the write queues until Cursor fully quits. Restart Cursor after it lands.

The gateway must be reachable through public HTTPS because Cursor's backend performs final prompt building and calls the custom endpoint. A loopback or LAN-only gateway cannot serve this lane. The gateway also needs a working upstream provider credential. Serving a Claude model behind anyray-default, for example, requires an Anthropic API key or another configured Claude API provider; the Cursor Team subscription is not that credential.

Best-effort settings automation

Cursor does not publish a managed-config format for its BYOK settings. Connect changes only the recognized, journaled app-state cells and refuses an unfamiliar shape. Verify after Cursor upgrades and use the manual steps below if the route no longer appears.

Verify the BYOK lane

Run anyray-connect status or anyray-connect doctor --verify. The lane is healthy only when the exact base URL, enable toggle, and personal ark_… credential match. Then send one eligible custom-model chat request and confirm its gateway inference trace. Agent wire behavior has changed across Cursor releases, so verify the exact installed version rather than promising feature-wide coverage.

Manual BYOK setup

1

Open settings

Cursor → Settings → Models → OpenAI API Key.

2

Override the base URL

Set Override OpenAI Base URL to https://gateway.example.com/v1/seat/cursor.

3

Set the key

Paste the personal ark_… key from anyray-connect print-key, then restart Cursor.

Routing boundary

The OpenAI override is the only supported Cursor inference seam that points at another base URL. It covers only requests Cursor elects to send through that custom-model endpoint; its Agent wire shape has varied by release. Native Team Claude/Opus, Tab, indexing, and other first-party traffic cannot be redirected. Cursor's agent acp command exposes Cursor CLI as an agent server for another client; it is not an inbound custom provider for Cursor.

For full request-level optimization of a subscription-backed Claude/Opus session, use Claude Code with a separate Claude Pro, Max, Team, or Enterprise entitlement. Claude Code officially supports subscription OAuth through an ANTHROPIC_BASE_URL gateway when the gateway forwards the OAuth beta capability. A Cursor Team entitlement cannot be used by Claude Code.

Spend visibility is not optimization

Cursor's official usage-event connector is metadata-only and cannot change native requests. The Team pricing page advertises Admin API usage statistics, but Cursor's API overview marks the Admin API Enterprise-only. Do not promise automatic Team-plan import until an admin:* key successfully calls /teams/filtered-usage-events. See Subscription spend connectors.