Cursor reference
Depth behind the Cursor guide.
Native-mode hook mechanics
| Seam | What it covers, and where it stops |
|---|---|
| Shell hook | Recognized simple shell commands with bulky output: test and search runs, read-only diagnostics (git log, git diff, docker logs, kubectl get), system logs, build output. On macOS and Linux it runs the command through Anyray's output reducer and preserves the exit code. It invokes the parsed executable directly and buffers up to 16 MiB before reducing, so a command relying on a shell alias can behave differently, and live output can lag. Streaming forms (docker logs -f, tsc --watch), complex commands, and anything on Windows fail open. |
| Read/Grep redirect | Cursor cannot rewrite a built-in tool's output, so the hook declines the call once and tells the agent to call anyray_read or anyray_search. Content arrives trimmed on the re-issue. Deliberately narrow: files of 16 KiB or more, targets inside the workspace, and at most one redirect per file or search per conversation, so a retry always gets through. |
| MCP results | Cursor's updated_mcp_tool_output field lets Anyray replace an oversized object-valued MCP result before the model consumes it. |
| No local stores | The hooks keep no cache or tee. The prompt hook can record an oversized-paste opportunity, but Cursor does not let it rewrite the submitted prompt. |
MCP tool parameters and bounds
anyray_search returns workspace matches that ride the postToolUse hook to the gateway, where
relevance_filter ranks and trims them to the query.
| Parameter | Range | Effect |
|---|---|---|
maxResults | 1–400 | Caps the hits. |
resultShape | paths, lines, full (default) | How much of each hit returns. On a 60-hit sweep those render as roughly 1,490 / 325 / 34 tokens. |
anyray_read returns a file the same way, but reversibly. The gateway leaves a retrieve ctx_…
handle, so the file comes back as the relevant slice with elided lines recoverable through
anyray_retrieve. Its optional focus ("the exported symbols") folds into that ranking.
Results are bounded before they leave the MCP server
An MCP host caps tool results and rejects an oversized one outright, so a result that overran would
reach the agent as an error carrying none of the content. Anyray bounds each result independently of
the gateway: a read that hits the bound is cut at a line boundary and names its own continuation
(anyray_read(path=…, startLine=…)), and a search drops its lowest-ranked matches and reports how
many it dropped. The gateway's ranking still runs on whatever comes back.
Steering agents to the optimized tools
anyray_search and anyray_read only optimize when the agent chooses them, and Cursor owns tool
selection. The preToolUse redirect already covers the most expensive case. A rule covers the rest.
| Scope | How |
|---|---|
| Per repository (automatic) | Run anyray-connect --tools cursor inside a git checkout. It writes .cursor/rules/anyray.mdc at the repo root with alwaysApply: true. Commit the file, and everyone who clones the repo shares the steer. |
| Team plan (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. |
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. Running outside a git repo is a silent no-op,
and a failed write never fails Cursor setup. Connect also prints the rule after setup.
A rule is steering, not enforcement. The hooks run regardless, so a user who never sees the rule is still covered on the bulky path.
BYOK payload shapes
The gateway's Cursor lane absorbs the payload shapes Cursor has sent to the OpenAI-override endpoint across releases: a Responses-API envelope on the chat path, flat tool definitions, and a request with no model (a Cursor 3.x Agent-mode bug). This is why a Cursor update does not turn into provider 400s.
Cloud agents
Cursor cloud agents do not load user-level ~/.cursor/hooks.json, Cursor currently defers its MCP
hooks there, and a cloud VM has neither the local Anyray binary nor the key. Native-mode setup covers
local Cursor Agent work only. Cursor's agent acp command exposes Cursor CLI as an agent server for
another client, and is not an inbound custom provider.
Spend visibility is not optimization
Cursor's official usage-event connector 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.
Cursor's own contracts
Hooks · Third-party hooks · Cloud agents · Bring your own API key · Token Rate