Claude Desktop

Claude Desktop (GUI) 연결 (Connect Claude Desktop to LiteLLM)

Claude Desktop의 서드파티 추론은 Cowork, Chat, Code 세션의 모든 모델 호출을 사용자가 지정한 게이트웨이로 보내고, 같은 게이트웨이를 통해 MCP 서버에 도달해요. 이 페이지는 가장 빠른 경로예요. 하나의 기기, 정적 가상 키, 앱에서 바로 구성. ID 제공자를 통한 단일 로그온(SSO), 모델 선택기 규칙, 플릿에 설정 롤아웃은 Claude Desktop (Cowork)을 보세요.

출처: 문서

본문

빠른 참조 (Quick reference)

설정	값
Inference provider	Gateway
게이트웨이 base URL	`<LITELLM_PROXY_BASE_URL>` (예: http://localhost:4000)
게이트웨이 API 키	LiteLLM 가상 키, auth scheme Bearer
MCP 엔드포인트	`<LITELLM_PROXY_BASE_URL>/mcp`, 또는 하나의 서버에 `<LITELLM_PROXY_BASE_URL>/<server_name>/mcp`
MCP auth 헤더	`x-litellm-api-key: *** <virtual key>`

LLM 설정 (LLM setup)

1. 개발자 모드 활성화 (Enable Developer Mode)

Claude Desktop에서 Help -> Troubleshooting -> Enable Developer Mode를 여세요.

2. 서드파티 추론 구성 열기 (Open Configure Third-Party Inference)

Claude 메뉴를 열고 Developer를 클릭한 다음 Configure Third-Party Inference...를 클릭하세요.

3. 게이트웨이 URL과 가상 키 입력하기

Connection 섹션에서 Inference provider를 Gateway로 설정하고, LiteLLM 프록시 URL을 Gateway base URL에, 가상 키를 Gateway API key에 넣고, Gateway auth scheme은 bearer(기본)로 두세요 (LiteLLM은 x-api-key도 수락). Apply Changes(구버전에서는 Apply locally) 클릭.

가상 키가 없다면 Admin UI의 Virtual Keys -> + Create New Key에서 생성하세요. Claude 모델로 범위를 지정하고 max_budget을 주세요. 같은 키를 쓰는 모든 사람이 그 예산을 공유해요.

4. 검증 (Verify)

Claude Desktop을 재시작하세요. 모델 선택기는 게이트웨이의 GET /v1/models에서 만들어지고, claude나 anthropic을 포함하는 model_name 값을 유지하므로, 배포 이름을 그에 맞게 지으세요. 작업을 시작한 다음 Admin UI의 Logs 또는 Usage에서 가상 키에 귀속된 요청을 확인하세요.

MCP 설정 (MCP setup)

아래 MCP 스크린샷은 Linux의 Claude Desktop 2.2553.13과 로컬 데모 게이트웨이를 사용해요. 메뉴 라벨은 앱 버전에 따라 다를 수 있어요.

1. 게이트웨이 커넥터 추가하기

Configure Third-Party Inference를 열고 Connectors를 찾으세요. litellm이라는 서버를 추가하고, Streamable HTTP를 선택하고, URL에 http://localhost:4000/mcp를 입력하세요. base URL을 게이트웨이 주소로 바꾸세요. 이 엔드포인트는 키가 액세스할 수 있는 서버를 노출해요.

x-litellm-api-key 헤더를 Bearer <your virtual key>로 설정하세요. overview에서 설명한 대로 키에 그 MCP 서버 액세스를 부여하세요. 내보낸 구성에서 이는 managedMcpServers:의 항목이에요:

[
  {
    "name": "litellm",
    "transport": "http",
    "url": "http://localhost:4000/mcp",
    "headers": {"x-litellm-api-key": "Bearer sk-1234"}
  }
]

2. 연결 테스트하기

Sign in & test(일부 버전에서는 Test this connection)를 클릭하세요. Claude는 입력한 URL과 자격 증명으로 MCP 초기화와 도구 발견을 실행한 다음, 발견한 도구 또는 연결 오류를 표시해요. 구성을 저장하기 전에 도구가 의도한 서버에 속하는지 확인하세요.

스크린샷은 로컬 데모 키 sk-1234를 사용해요. 자체 가상 키를 사용하세요. Claude는 정적 인증 헤더를 자격 증명처럼 표시할 수 있어요. 관리형 배포에서는 고급 가이드가 대신 credential helper를 다뤄요.

3. Cowork에서 검증하기

구성을 적용하고 Claude Desktop을 재시작하세요. 커넥터의 읽기 전용 도구를 사용하는 Cowork 작업을 시작하고, 요청되면 승인하고, 도구가 결과를 반환하는지 확인하세요. 도구는 <server>-<tool> 명명 규칙을 사용해요.

하나의 서버를 선택하려면 /<server_name>/mcp를 대신 사용하세요. MCP configuration reference가 엔드포인트 선택, 서버 필터링, 인증을 다뤄요.

Claude Desktop의 내장 커넥터(github, microsoft365, websearch)는 앱 안에서 그 공급업체 API에 대해 실행되며 LiteLLM을 절대 통과하지 않아요. url 항목만 통과해요. 사용자 자신의 업스트림 로그인이 필요한 서버에는 개별 서버 URL에 "oauth": true를 설정하고 LiteLLM이 플로우를 실행하게 하세요. MCP OAuth passthrough 참고. 전체 가이드는 SSO 플릿용 headersHelper와 툴별 정책을 다뤄요.

다음 단계 (Next steps)

Claude Desktop (Cowork)에서 SSO, 모델 선택기 규칙, 플릿 롤아웃, 문제 해결을, Auto Router with Claude Code and Claude Desktop, MCP gateway reference를 보세요.