Cursor 통합

Cursor 통합

Cursor IDE 요청을 LiteLLM을 통해 라우팅해 통합 로깅, 예산 제어, 그리고 어떤 모델이든 접근할 수 있게 하는 방법을 알려드릴게요. Cursor를 MCP 도구에 연결하려면 MCP 구성 참조에서 다이렉트 클라이언트 URL과 헤더를 사용해요.

출처: 문서

본문

info

지원 모드: Ask, Plan, Agent. base URL 오버라이드에서 에이전트 모드는 LiteLLM v1.97.0+가 필요해요. 이 버전이 Cursor의 에이전트가 보내는 Responses API 요청 형태를 chat completions 경로로 번역해요. Cursor는 자체적으로 커스텀 API 키를 모드와 모델별로 게이트하므로, 커버리지는 Cursor가 활성화하는 것에 따라 달라져요.

Cursor는 AI Gateway를 공식적으로 지원하지 않아요. 여기서의 작업은 그들의 API를 리버스 엔지니어링한 최선의 노력이에요. Cursor CLI(agent / cursor-agent)는 LiteLLM을 전혀 대상으로 할 수 없으니 Cursor CLI를 참고하세요.

Override OpenAI Base URL이 없나요?

새로운 Cursor 빌드는 더 이상 모든 플랜에서 Override OpenAI Base URL 설정을 보여주지 않아요. Cursor에 이 설정이 없다면, 이 섹션의 설정 대신 아래의 Azure OpenAI 폴백을 사용해요.

빠른 참조

| 설정 | 값 | | Base URL | ``- /cursor` | | API 키 | LiteLLM 가상 키 | | 모델 | LiteLLM의 Public Model Name |

설정

1. Base URL 구성

Cursor → Settings → Cursor Settings → Models를 열어요.

Override OpenAI Base URL을 활성화하고 /cursor와 함께 프록시 URL을 입력해요.

https://your-litellm-proxy.com/cursor

프록시는 인터넷에서 접근 가능해야 해요. Cursor는 사용자 머신이 아니라 자체 서버에서 요청을 보내며 User-Agent: Cursor/1.0을 사용해요. VPN이나 IP 허용 목록 뒤에 있거나 비공개 주소에 있는 프록시는 요청이 LiteLLM에 도달하기 전에 Cursor 쪽에서 실패해요. 각 경우에 Cursor가 보여주는 것은 문제 해결(Troubleshooting)에서 알려드릴게요.

2. 가상 키 생성

LiteLLM Dashboard에서 Virtual Keys → + Create New Key로 이동해요.

키 이름을 정하고 접근할 수 있는 모델을 선택해요.

Create Key를 클릭하고 즉시 복사해요. 다시 볼 수 없거든요.

Cursor의 OpenAI API Key 필드에 붙여넣어요.

3. 커스텀 모델 추가

Cursor Settings에서 + Add Custom Model을 클릭해요.

LiteLLM Dashboard → Models + Endpoints에서 Public Model Name을 가져와요.

이름을 Cursor에 붙여넣고 토글을 활성화해요.

내장 모델 이름

Cursor는 내장 모델 중 하나와 이름이 같은 커스텀 모델을 The model "X" is already available as "Y"로 거부해요. Cursor는 어떤 요청도 LiteLLM에 도달하기 전에 이 검사를 로컬에서 실행해요. 같은 배포 대상에 대해 구별되는 공용 모델 이름을 가진 model_list 엔트리를 추가하고 그 이름을 Cursor에서 사용해요.

model_list:  - model_name: litellm-claude-sonnet-5    litellm_params:      model: anthropic/claude-sonnet-5

모델 변형

Cursor의 모델 선택기는 모델 이름의 thinking 및 fast 변형을 만들 수 있어요. 예: claude-opus-5-thinking. LiteLLM v1.97.0+는 이 접미사를 자동으로 기본 모델로 해석하므로, 키 스코프와 모델별 예산이 해석된 모델에 적용되고 변형을 위한 별도의 model_list 엔트리가 필요하지 않아요.

4. 테스트

Cmd+L / Ctrl+L로 Ask 모드를 열고 모델을 선택해요.

메시지를 보내요. 이제 모든 요청이 LiteLLM을 통해 라우팅돼요.

폴백: Azure OpenAI 설정

Cursor 빌드에 Override OpenAI Base URL 설정이 없으면, Cursor의 Azure OpenAI 설정이 여전히 커스텀 base URL을 받아들이고 트래픽을 LiteLLM 프록시로 라우팅해요. 이 경로는 LiteLLM의 Azure 호환 /openai/deployments//chat/completions 라우트를 사용하는데, 이는 2023년부터 LiteLLM에 있었으므로 프록시 업그레이드가 필요 없어요. Ask, Plan, Agent 모드가 모두 그 위에서 동작해요(Cursor 3.17.21에서 확인). Cursor의 Azure 클라이언트는 에이전트 모드에서도 일반 chat completions 요청을 보내므로, base URL 오버라이드 경로의 v1.97.0 요구 사항은 여기 적용되지 않아요.

| 설정 | 값 | | Base URL | ``- (/cursor 접미사 없음) | | Deployment Name | LiteLLM의 Public Model Name | | API 키 | LiteLLM 가상 키 |

1. Azure OpenAI 활성화

Cursor → Settings → Cursor Settings → Models를 열고 API Keys를 펼친 뒤 Azure OpenAI 토글을 활성화해요. Cursor가 일부 기능은 API 키로 청구할 수 없다는 확인 대화상자를 보여주면 확인해요.

필드를 채워요:

  • Base URL: LiteLLM 프록시 URL, 예: https://your-litellm-proxy.com. /cursor를 붙이지 마세요. 프록시는 인터넷에서 접근 가능해야 해요. Cursor는 사용자 머신이 아니라 백엔드에서 요청을 보내요.

  • Deployment Name: 사용할 LiteLLM 공용 모델 이름, 예: claude-sonnet-5. 이것이 모든 요청을 서빙할 모델을 결정해요(아래 경고 참고).

  • API Key: LiteLLM 가상 키.

2. 커스텀 모델 추가

Azure OpenAI 토글이 켜져 있는 동안에는 커스텀 모델만 동작해요. Cursor는 자체 모델(Composer, Cursor Grok)을 This model does not support custom API keys로 거부하고, 내장 Claude와 GPT 모델은 여전히 프록시로 라우팅하지만 채팅 완료 배포 라우트가 거부하는 Anthropic Messages 또는 Azure Responses 형식이라서 그 채팅은 멈춰요. + Add Custom Model을 클릭하고 내장 모델과 충돌하지 않는 이름(예: litellm-claude)을 입력한 뒤 활성화하고 채팅 모델 선택기에서 선택해요.

Cursor 구독에서 Composer나 다른 내장 모델을 사용하려면 Azure OpenAI 토글을 꺼요. 다시 LiteLLM으로 라우팅하려면 다시 켜요.

Deployment Name이 모델을 결정해요

이 경로에서 Cursor는 모든 요청을 /openai/deployments//chat/completions로 보내고, LiteLLM은 경로가 지명하는 모델을 서빙해요. Cursor에서 선택한 커스텀 모델은 라벨일 뿐이에요. 다른 커스텀 모델을 선택해도 어떤 모델이 답하는지는 바뀌지 않아요. 모델을 전환하려면 Azure OpenAI 설정에서 Deployment Name을 편집해요. 선택기가 잘못 안내하지 않도록 활성화된 커스텀 모델 하나를 유지해요.

3. 테스트

Ask 모드에서 메시지를 보낸 뒤 Agent 모드를 시도해요. 요청은 LiteLLM 로그에 /openai/deployments//chat/completions의 chat completions로 표시되고, 배포의 모델에 귀속돼요.

MCP 서버 연결

LiteLLM Proxy를 통해 MCP 서버를 Cursor에 연결할 수도 있어요.

Cursor와 MCP 통합 구성에 대한 공식 지침은 Cursor 문서를 참고해요: https://cursor.com/en-US/docs/context/mcp.

  • Cursor Settings의 "Tools & MCP" 탭으로 가서 "New MCP Server"를 클릭해요.

  • mcp.json에 다음 구성을 추가해요.

{  "mcpServers": {    "litellm": {      "url": "http://localhost:4000/everything/mcp",      "type": "http",      "headers": {        "Authorization": "Bearer «redacted:sk-…»"      }    }  }}
  • 이제 LiteLLM의 MCP가 Cursor의 "Installed MCP Servers" 아래에 나타나요.

Cursor Cloud Agents

LiteLLM은 Cursor Cloud Agents API 앞에 설 수도 있어요. 그러면 api.cursor.com 위에 실행되는 에이전트도 같은 자격 증명 관리와 로깅을 받아요. Cursor Cloud Agents를 참고하세요.

Cursor CLI (cursor-agent)

Cursor CLI(agent, cursor-agent로도 설치됨)는 LiteLLM이나 다른 게이트웨이를 대상으로 할 수 없어요. 그 --endpoint 플래그와 CURSOR_API_ENDPOINT 변수는 OpenAI 호환 API가 아니라 CLI가 로그인할 Cursor 백엔드를 선택해요. 시작 시 CLI가 사용자의 키를 /auth/exchange_user_api_key에 POST해 Cursor 세션 토큰으로 교환하고, 그 이후의 모든 요청은 Cursor 전용 RPC예요. Cursor는 이 플래그를 문서화하지 않고, CLI에 커스텀 엔드포인트나 OpenAI 호환 키를 제공하지도 않아요(공개 기능 요청). 유일한 자체 자격 증명(BYO) 옵션인 agent bedrock조차 Cursor의 백엔드를 통해 라우팅돼요.

CLI를 프록시에 가리키면 어떤 모델에도 도달하기 전에 실패해요(공개 Cursor CLI 2026.08.31 빌드에서 확인):

export CURSOR_API_KEY=
- agent --endpoint https://your-litellm-proxy.com

⚠ Warning: The provided API key is invalid.The API key was loaded from the CURSOR_API_KEY environment variable.Please check you have the right key, create a new one, or authenticate without it.

CLI는 Cursor 세션 토큰을 담지 않은 500 미만의 어떤 응답에도 이 경고를 출력해요(5xx는 고정된 Failed to reach the Cursor API 오류를 대신 받음). 그래서 그 라우트가 없는 프록시(LiteLLM은 루트에서 404, /cursor 아래에서 401로 응답)는 잘못된 Cursor 키와 똑같이 보이고, 프록시의 어떤 텍스트도 화면에 도달하지 않아요. Cursor를 LiteLLM으로 라우팅하려면 이 페이지의 Cursor IDE 설정을 사용하고, 커스텀 엔드포인트를 지원하는 터미널 에이전트가 필요하면 Claude Code, Codex CLI, Gemini CLI, OpenCode를 참고하세요.

문제 해결

| 이슈 | 해결 방법 | | 모델이 응답하지 않음 | base URL이 /cursor로 끝나는지, 키가 모델 접근 권한을 가졌는지 확인 | | Cursor CLI(agent / cursor-agent)에서 The provided API key is invalid | Cursor CLI는 게이트웨이를 사용할 수 없음: --endpoint는 OpenAI 호환 API가 아니라 Cursor 백엔드를 선택하므로 Cursor의 인증 라우트가 없는 어떤 프록시에서도 이 경고로 로그인이 실패함. Cursor CLI 참고 | | Invalid API key / Unauthorized User API key | 프록시가 401로 응답할 때 Cursor가 이걸 보여줌. API Key 필드는 LiteLLM 가상 키(sk-로 시작)여야 하며, 플레이스홀더 값은 거부됨 | | User API Key Rate limit exceeded | Cursor가 프록시 요청에서 429나 5xx를 받을 때, 그리고 전혀 응답을 못 받을 때도 이걸 보여줌. VPN이나 IP 허용 목록이 Cursor 서버의 트래픽을 버릴 때가 그렇고(Cursor 3.18.25에서 확인: 채팅이 약 1분간 Taking longer than expected에 머물다 이걸 표시). 따라서 원인이 종종 속도 제한이 아님. 먼저 네트워크 밖 머신에서 curl \n- /cursor/models -H "Authorization: Bearer\n*** " 실행. 멈추면 프록시가 인터넷에서 접근 불가능하고 LiteLLM이 요청을 본 적이 없음. 응답하면 LiteLLM 로그(User-Agent: Cursor/1.0로 도착)에서 실제 오류를 확인. 흔한 원인은 키의 rpm/tpm 한도(각 Cursor 요청이 약 25k 토큰의 시스템 프롬프트를 담으므로)와 제공자 429 | | Network Error / We're having trouble connecting to the model provider | base URL 호스트네임이 공용 인터넷에서 해석되지 않음(예: 내부 DNS 이름). Cursor가 약 1분간 재시도하는 동안 Rate limited by model provider, retrying을 보여주다 이걸 표시. 공용 DNS가 해석하는 호스트네임을 사용 | | Provider returned error: Access to private networks is forbidden | base URL이 비공개 주소(10.x, 192.168.x, localhost 등)를 가리키며 Cursor 서버가 호출을 거부함. 프록시를 공용 주소에 배치 | | Agent 모드가 동작하지 않음 | LiteLLM v1.97.0+로 업그레이드하고 모델이 Cursor에서 커스텀 API 키를 지원하는지 확인 | | Cursor이 LiteLLM 모델을 나열하지 않음 | GET /cursor/models를 서빙하는 LiteLLM v1.97.0+로 업그레이드. 이전 버전은 그 라우트를 서빙하지 않고 401 또는 404로 응답. curl \n- /cursor/models -H "Authorization: Bearer\n*** "로 확인 | | The model "X" is already available as "Y" | Cursor가 내장 모델과 일치하는 이름을 차단함. 구별되는 공용 모델 이름으로 모델 추가(3단계의 경고 참고) | | This model does not support custom API keys | 커스텀 API 키가 활성화된 상태에서 Cursor 네이티브 모델(Composer, Cursor Grok)을 선택함. 추가한 커스텀 모델을 선택하거나, 구독으로 Cursor 모델을 쓰려면 Azure OpenAI 토글 비활성화 | | Azure OpenAI가 활성화된 상태에서 내장 모델을 선택하면 채팅이 멈춤 | Cursor가 여전히 내장 Claude/GPT 모델을 배포 라우트가 거부하는 형식으로 프록시에 라우팅함. 추가한 커스텀 모델을 선택 | | Override OpenAI Base URL 설정 없음 | Cursor 빌드가 이 설정을 제공하지 않음. Azure OpenAI 폴백 사용 | | Azure 폴백이 항상 같은 모델로 응답 | 예상된 동작: Deployment Name이 어떤 커스텀 모델을 선택하든 모델을 결정. 전환하려면 Deployment Name 편집 |

더 알아보기 (Learn more)