cursor2api: An Anthropic and OpenAI Compatible Proxy for Cursor Docs AI

The gap cursor2api fills between Cursor's docs endpoint and Claude Code

Cursor publishes an AI chat endpoint behind its documentation pages. It speaks Cursor's own request and response shape, not the Anthropic or OpenAI wire formats. That is a problem if your tooling expects one of those two standards.

Claude Code, for instance, talks to an Anthropic Messages API endpoint at /v1/messages. The README's architecture diagram shows the intended flow: Claude Code on the left sends Anthropic-shaped requests, cursor2api converts them, and the Cursor API at /api/chat answers. The same diagram routes Cursor IDE through /v1/responses and generic OpenAI-compatible clients through /v1/chat/completions. One process, three front doors, one upstream.

The target reader is someone who wants Claude Code or a Cursor IDE agent session to run against the Cursor docs endpoint rather than paying for a separate provider. The README's own first line is a warning worth repeating: as of 20260401, the Cursor docs page only offers gemini-3-flash. So the thing you are proxying is narrower than the feature list suggests.

How the protocol conversion actually works

The repository layout tells most of the story. src/converter.ts handles protocol conversion, prompt injection, context cleaning, and dynamic budgeting. src/handler.ts processes Anthropic requests and adds identity protection, refusal interception, and Thinking support. src/openai-handler.ts does the OpenAI and Cursor IDE side. src/cursor-client.ts is the upstream client, and the README says it carries a Chrome TLS fingerprint to look like a real browser.

Several mechanisms sit between request and response. Tool schemas are compressed from a full JSON Schema of roughly 135k characters into compact type signatures of roughly 15k characters, which is a context-saving measure rather than a correctness one. A tolerant JSON parser with five layers of fault tolerance handles code blocks embedded in JSON. Tool arguments get repaired by src/tool-fixer.ts, which maps field names such as file_path to path, replaces smart quotes, and does fuzzy matching.

On the response path the project layers refusal interception with more than 50 regex patterns in Chinese and English, retries with a rewritten prompt, and optionally sanitizes Cursor identity references into Claude ones. That last part is a deliberate design choice, and it is the kind of thing you should read carefully before enabling in any workflow where attribution matters.

Installing cursor2api and making your first Claude Code request

The README's quick start has four steps. Install dependencies first. Note that package.json defines a postinstall script that installs stealth-proxy dependencies and runs npx playwright install chromium, so the install is heavier than a typical Node project.

npm install

Copy the example config, then edit it. The README documents port 3010 as the default, cursor_model defaulting to anthropic/claude-sonnet-4.6, and auth_tokens as a list that, when unset, lets every caller through.

cp config.yaml.example config.yaml

Start the server. Development mode uses tsx watch; production compiles TypeScript then runs the built output.

# development
npm run dev

# production
npm run build && npm start

Point Claude Code at it. With no auth_tokens configured, the base URL is enough.

export ANTHROPIC_BASE_URL=http://localhost:3010
claude

If you did set auth_tokens, add the matching key. The README's example uses sk-your-secret-token-1, which must match an entry in the config list.

export ANTHROPIC_BASE_URL=http://localhost:3010
export ANTHROPIC_API_KEY=sk-your-secret-token-1
claude

For Cursor IDE the README says to set OPENAI_BASE_URL to a publicly reachable HTTPS domain that reverse-proxies to cursor2api, not localhost or a LAN address, and that Cursor Pro is usually required for custom base URLs. After startup, http://localhost:3010/logs opens the log viewer, which the README describes as an SSE-driven timeline covering receive, convert, send, response, and complete.

The truncation problem and the three mechanisms aimed at it

Long tool calls get cut off. v2.7.8 introduced three mechanisms under the heading of anti-truncation, and the README states all three are off by default and enabled on demand. That default matters: if you upgrade and see no behavioural change, this is why.

Context Pressure Inflation inflates the reported input_tokens so that Claude Code triggers its own automatic compaction earlier. Adaptive History Budget reserves more output space as the tool count grows; the README gives the example that 90 tools reserve roughly 8K more tokens. Intelligent Tool Result Truncation applies different head and tail ratios depending on tool type, with Read, Bash, and Search treated differently.

The adjacent setting to watch is max_auto_continue, which defaults to 0. In that state the Anthropic path hands truncation recovery back to the client, while the README says OpenAI-compatible long tool calls still get one internal recovery attempt as a floor. If you are chasing a cutoff in Claude Code, the interaction between max_auto_continue and the three new mechanisms is the first place to look.

Where cursor2api is the wrong tool

The dependency on an undocumented endpoint is the central risk, and the README does not hide it. The model list has already shrunk to gemini-3-flash. Anything built on top inherits that instability, and no amount of retry logic in src/handler.ts fixes an upstream that stops answering.

Second, the identity and refusal machinery is opinionated. Response sanitization rewrites Cursor identity references to Claude, and refusal interception retries with a cognitively reframed prompt. Both are configurable, but if your use case depends on knowing exactly what the upstream model said and why it declined, this layer is between you and the truth.

Third, the operational surface is not small. The Dockerfile pulls in Playwright Chromium with system dependencies, tesseract.js for local OCR, better-sqlite3, and js-tiktoken, and sets NODE_OPTIONS to --max-old-space-size=4096. The README also notes the image does not bundle config.yaml. If you want a single small container, this is not it.

How cursor2api differs from running a standard OpenAI-compatible gateway

A conventional gateway such as LiteLLM or one-api sits in front of providers that publish a stable API contract. You register keys, map model names, and the gateway forwards. The hard part is quota and routing.

cursor2api solves a different problem. There is no published contract to forward against, so the work is translation and repair: converting Anthropic Messages into Cursor's shape, compressing tool schemas, fixing malformed tool arguments, recovering truncated Write and Edit calls, and detecting refusals so they can be retried. That is why the repository has a converter, a tool-fixer, a tolerant parser, and a refusal pattern list rather than a routing table.

The practical consequence is that cursor2api is not a drop-in replacement for a gateway. It is a compatibility shim for one specific upstream. If your upstream is OpenAI, Anthropic, or a self-hosted model with a documented API, a standard gateway is the simpler choice and will not break when someone edits a documentation page.

Licence, maintenance, and what an upgrade costs you

The project is MIT licensed. That permits commercial use, modification, and redistribution provided the copyright notice and permission notice are included. It offers no patent grant and no warranty, and it says nothing about the terms under which Cursor's own endpoint may be used; that question sits outside the repository and outside this article.

The last push to the default branch was on 2026-06-01, and the repository is not archived. The most recent tagged release listed is v2.7.8 from 2026-03-27. Maintenance is therefore best described by those dates rather than by any claim about how active the project is.

Upgrade cost is moderate. Configuration lives in config.yaml with environment variable overrides, and the README warns that log persistence changes require a container restart. The test surface is unusually broad for a project this size: package.json defines test:unit, test:tool-fixer, test:openai-compat, test:vision, test:e2e, and test:agentic, plus a test:all script that chains ten unit files. Running test:all after an upgrade is the cheapest way to catch a regression in parsing or protocol conversion before it reaches a live session.

Editorial conclusion

Adopt cursor2api if you already run Claude Code or a Cursor IDE workflow and want to point it at the Cursor docs endpoint without writing your own protocol translation layer; the /v1/messages and /v1/chat/completions handlers, the tool-fixer, and the log viewer at /logs are the parts that save real work. Do not adopt it if you need a stable, contract-backed model provider: the README itself notes the docs page had been reduced to gemini-3-flash, and the whole design assumes an undocumented endpoint that can change without notice. Before deploying, verify which models /v1/models actually returns on your machine, confirm whether auth_tokens is set (the default is open to all callers), and check that your Cursor session token still works against the current endpoint.

Frequently asked questions

Official sources

1. 7836246/cursor2api on GitHub
2. License: MIT
3. Project website
4. README
5. Releases