> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor

> Set up Cursor with the TrueFoundry AI Gateway for AI-powered development.

[Cursor](https://cursor.sh/) is an AI code editor built on VS Code. This page covers how to connect Cursor to the TrueFoundry AI Gateway using the **Override Base URL** setting with the **Databricks** model provider.

## BYOK Works, Override Base URL Only Works with Databricks

Cursor offers two ways to connect to models:

* **BYOK (Bring Your Own Key)** — You enter your API key directly in Cursor settings without changing the base URL. This works as expected.
* **Override Base URL** — You change the OpenAI base URL to point to a custom gateway or proxy. This **only works with the Databricks model provider** as described below.

<CardGroup cols={2}>
  <Card title="What Works" color="#16a34a" icon="check">
    **Databricks Provider with Override Base URL** — Create a Databricks model provider account with the `/cursor/v1` base URL and add your TrueFoundry API key in Cursor settings.
  </Card>

  <Card title="What Breaks" color="#dc2626" icon="xmark">
    **Other Providers with Override Base URL** — OpenAI, Anthropic, and Gemini providers send incompatible request formats to `/chat/completions`, and no amount of proxying can reliably fix it.
  </Card>
</CardGroup>

<Warning>
  The Override Base URL approach has compatibility issues with non-Databricks providers that will cause requests to fail. The integration described below uses the Databricks provider which handles Cursor's request format correctly.
</Warning>

## Prerequisites

Before integrating Cursor with TrueFoundry, ensure you have:

1. **TrueFoundry Account**: Create a [TrueFoundry account](https://www.truefoundry.com/register) and follow the instructions in our [Gateway Quick Start Guide](https://docs.truefoundry.com/gateway/quick-start)
2. **Databricks Provider Account**: Create a Databricks model provider account in TrueFoundry with the base URL set to:
   ```
   https://<workspace-url>/ai-gateway/cursor/v1
   ```
3. **Models Configured**: Add the models you want to use to the Databricks provider account on the TrueFoundry platform
4. **Cursor Installed**: Install [Cursor](https://cursor.sh/) on your machine

## Integrate TrueFoundry with Cursor

<Steps>
  <Step title="Open Cursor Settings">
    Open Cursor and navigate to **Cursor Settings** → **Models**.
  </Step>

  <Step title="Add API Key and Base URL">
    Scroll to the **API Keys** section at the bottom and configure:

    * **OpenAI API Key**: Enter your TrueFoundry API key (Personal Access Token)
    * **OpenAI Base URL**: Enter `{GATEWAY_BASE_URL}/cursor/v1`
  </Step>

  <Step title="Add Custom Models">
    Add the custom models you configured on the TrueFoundry platform. Use the exact **Model ID** from your TrueFoundry model configuration as the model name in Cursor.
  </Step>
</Steps>

## Important Precautions

<Warning>
  Follow these guidelines to avoid common integration issues:
</Warning>

* **Model name must match Model ID** — When adding custom models in Cursor, use the exact same name as the Model ID configured on the TrueFoundry platform.
* **Avoid reserved words in provider account name** — Do not use words like `GPT`, `Claude`, or `Gemini` in your Databricks model provider account name. Cursor uses these keywords internally to determine request formatting, which can cause unexpected behavior.
* **Cursor-only integration** — This integration works exclusively within the Cursor IDE. It will not work on the TrueFoundry Playground or any other interface.

## What Goes Wrong with Other Providers

When you override the base URL, Cursor still sends requests to the `/chat/completions` endpoint. But the request body format it sends **does not match** the Chat Completions spec. The format changes depending on the model you select:

* **OpenAI models** — Cursor sends requests in the [Responses API](https://platform.openai.com/docs/api-reference/responses) format. It uses `input` instead of `messages`, sends flat tool definitions, and includes parameters like `store`, `previous_response_id`, and `truncation` that don't belong in Chat Completions.
* **Anthropic models** — Cursor sends requests in the native Anthropic format with Responses API structure on top, while still targeting the `/chat/completions` endpoint.
* **Gemini models** — Similar behavior. Cursor sends Gemini specific formatting that does not follow the Chat Completions spec.

<Note>
  In all cases, the endpoint is `/chat/completions` but the payload is something else entirely. This is the root cause of failures with non-Databricks providers.
</Note>

## Why a Proxy Does Not Fix This

You might think you can set up a proxy to intercept and transform these requests. This does not work reliably for two reasons:

1. **The request format is unpredictable.** Cursor mixes Responses API fields, native model formats, and custom tool types (`"type": "custom"`). Transforming all of this into valid Chat Completions format requires heavy and fragile patching.
2. **Cursor expects strict Chat Completions responses.** Even if you fix the request, Cursor will reject any response that does not exactly match the Chat Completions response format. So you need to transform both directions perfectly.

## No Support for Thinking Tokens

<Note>
  The Chat Completions API does not support thinking or reasoning tokens. Even if you get requests flowing through a proxy, the model's reasoning process cannot be shown in Cursor's UI.

  This matters because thinking tokens give visibility into how the model arrives at its answer. Without them, the experience feels like a black box.
</Note>

<Info>
  The underlying issue with non-Databricks providers is tracked by the Cursor team. See the [Cursor Community Forum thread](https://forum.cursor.com/t/cursor-agent-sends-responses-api-format-to-chat-completions-endpoint/153019) for technical details and discussion.
</Info>