Databricks Unity Gateway CLI 설치와 코딩 에이전트 관리 가이드

9월 30, 2026

Codex, Claude Code, Gemini CLI처럼 서로 다른 AI 코딩 도구를 팀에서 함께 쓰기 시작하면 문제는 모델 선택보다 운영에서 생깁니다. 누가 어떤 모델과 MCP 서버를 쓸 수 있는지, 로컬 설정이 최신 정책과 맞는지, 예산이 얼마나 남았는지, 실패한 도구 호출을 어디서 추적할지를 도구마다 따로 관리해야 하기 때문입니다.

Databricks가 2026년 9월 24일 발표한 Unity Gateway CLI는 이 문제를 다루는 명령줄 도구입니다. 개발자는 익숙한 코딩 에이전트를 계속 사용하고, 관리자는 모델·MCP 서버·스킬·비용 정책·추적 설정을 중앙에서 게시합니다. CLI 명령은 ug이며, 공식 문서 기준으로 Codex, Claude Code, Gemini CLI, OpenCode, GitHub Copilot CLI, Pi를 실행할 수 있습니다. Cursor Agent는 모델 연결이 아니라 MCP와 스킬 설정 범위로 지원됩니다.

핵심만 먼저 보면: 개인이 무료 코딩 도구를 하나 더 설치하는 방식이 아니라, 이미 Databricks 워크스페이스와 Unity Catalog를 운영하는 조직이 여러 코딩 에이전트에 같은 통제 기준을 적용하는 도구입니다. Python 3.12 이상과 uv, 워크스페이스 접근 권한이 필요하며, 관리형 에이전트 구성과 통합 추적의 일부 기능은 아직 Beta 또는 Preview 조건이 있습니다.

여러 AI 코딩 에이전트가 중앙 게이트웨이를 거쳐 승인된 모델, MCP 도구, 스킬, 예산 및 추적 정책에 연결되는 구조 — 개발자는 서로 다른 에이전트를 사용하지만 모델·도구·비용·추적 정책은 하나의 관리 경계에서 적용할 수 있습니다.

Unity Gateway CLI가 해결하려는 문제

코딩 에이전트는 각자 설정 파일, 인증 방식, 모델 이름, MCP 등록 위치가 다릅니다. 개인 실험에서는 한 번 설정하면 끝날 수 있지만, 팀 단위에서는 다음과 같은 불일치가 생깁니다.

개발자마다 승인되지 않은 모델이나 MCP 서버를 추가해 권한 경계가 달라집니다.
새 모델이나 비용 정책을 적용하려면 여러 도구의 설정을 각각 바꿔야 합니다.
로컬 도구 호출과 모델 요청이 서로 다른 로그에 남아 한 작업의 실패 원인을 연결하기 어렵습니다.
예산 초과를 발견해도 이미 실행 중인 에이전트와 새 세션에 같은 방식으로 대응하기 어렵습니다.

ug는 에이전트를 완전히 새 인터페이스로 바꾸지 않습니다. 실행 전에 워크스페이스에 게시된 구성을 가져와 인증과 로컬 설정을 맞춘 뒤, 선택한 에이전트의 기존 인터페이스를 엽니다. 관리자가 기본 에이전트나 모델을 바꾸면 다음 실행 때 구성이 동기화됩니다. 즉, 개발 경험을 하나로 통일하기보다 에이전트 앞단의 정책과 연결 방식을 통일하는 접근입니다.

시작 전 준비사항과 권한

항목	확인할 내용
로컬 환경	Python 3.12 이상, `uv`. 에이전트 자동 설치가 필요한 경우 `npm`도 필요합니다.
Databricks	워크스페이스 URL과 사용할 모델 서비스에 대한 접근 권한이 필요합니다.
관리형 구성	관리자가 공통 구성을 게시하려면 Unity Gateway Managed Configuration Preview를 활성화해야 합니다.
MCP·스킬	목록에 보이는 것과 실제 데이터 접근 권한은 별개입니다. 서버, 함수, 데이터, 외부 서비스 권한을 함께 확인해야 합니다.
통합 추적	Enhanced Unity Gateway Preview, Unity Catalog, 메타스토어 관리자 설정이 필요합니다. 추적 테이블은 기본적으로 생성한 관리자만 읽을 수 있습니다.

개인 액세스 토큰(PAT)도 지원되지만 기본 흐름은 워크스페이스 로그인과 OAuth입니다. PAT를 쓴다면 토큰을 명령에 직접 붙이지 말고 Databricks CLI 프로필에 저장한 뒤 ug configure --profile <이름> --use-pat 형태로 연결하는 편이 안전합니다.

설치부터 첫 실행까지

명령은 프로젝트 폴더를 연 터미널에서 입력합니다. 공식 빠른 시작 문서의 기본 순서는 다음과 같습니다.

uv tool install git+https://github.com/databricks/unity-gateway
ug --version

# 원하는 에이전트 실행
ug codex
# 또는
ug claude

ug --version에서 버전이 표시되면 설치 단계가 끝난 것입니다. 첫 실행에서는 사용할 Databricks 워크스페이스를 고르고 로그인합니다. 이후 ug가 에이전트별 설정 파일을 만들거나 관리하고, 연결을 마친 다음 Codex 또는 Claude Code의 익숙한 화면을 엽니다.

Databricks 공식 문서의 Unity Gateway CLI 설치와 에이전트 실행 명령 화면 — 공식 빠른 시작 문서의 설치·실행 단계. 출처: Databricks Docs, 2026년 9월 30일 확인.

조직이 게시한 관리형 구성이 없다면 대화형 설정을 사용할 수 있습니다. 특정 워크스페이스를 명시하거나 적용할 에이전트를 좁히는 명령도 있습니다.

ug configure
ug configure --workspace https://your-workspace.databricks.com
ug configure --agents claude,codex

설정 변경이 실제 파일을 건드리기 전에 보고 싶다면 저장소 README에 안내된 ug configure --dry-run을 사용할 수 있습니다. 문제가 생겼을 때는 ug doctor로 설치와 에이전트 설정을 점검하고, ug revert로 ug가 백업한 설정 파일을 복원할 수 있습니다. 기존 사용자 설정을 무조건 덮어쓴다고 가정하지 말고, 팀 적용 전 별도 테스트 계정과 테스트 장비에서 생성·변경되는 파일을 확인하는 것이 좋습니다.

MCP 서버와 스킬을 같은 기준으로 배포하기

MCP 서버는 에이전트가 데이터와 서비스에 접근하는 통로이고, 스킬은 특정 업무를 수행하는 재사용 지침입니다. ug는 둘을 같은 것으로 취급하지 않습니다. MCP는 연결을 등록하고, 스킬은 로컬 폴더에 내려받거나 MCP를 통해 게시된 레지스트리에서 읽게 할 수 있습니다.

# 접근 가능한 MCP 서버 선택
ug mcp add
ug mcp list

# 게시된 스킬 선택 및 다운로드
ug skills add
ug skills list

이름을 정확히 아는 경우 ug mcp add --names system.ai.github,system.ai.slack처럼 전체 Unity Catalog 이름을 지정할 수 있습니다. 스킬은 사용자 홈의 에이전트 스킬 폴더에 받을 수도 있고, ug skills add --path "$PWD"로 현재 프로젝트 안에 내려받아 저장소 단위로 검토할 수도 있습니다.

여기서 중요한 보안 원칙은 등록 가능과 실행 가능을 구분하는 것입니다. 목록에 서버가 보인다고 해서 그 서버 뒤의 저장소, Slack, 데이터베이스에 자동으로 접근할 수 있는 것은 아닙니다. 반대로 MCP 연결 자체가 승인됐더라도 도구 설명과 입력값에 민감 정보가 포함될 수 있습니다. 최소 권한, 읽기 전용 시작, 변경 작업 승인, 비밀정보 마스킹, 도구별 감사 로그를 함께 설계해야 합니다.

에이전트별 지원 범위가 같은 것은 아니다

공식 지원 표에서 Claude Code와 Codex CLI는 Databricks 모델, 외부 공급자, MCP, 스킬을 모두 지원하는 것으로 안내됩니다. 하지만 모든 에이전트가 동일하지는 않습니다.

Cursor Agent: ug cursor는 MCP와 스킬 설정 범위이며 모델 요청은 Cursor 계정을 사용합니다.
GitHub Copilot CLI: Databricks 모델과 MCP·스킬은 지원하지만 외부 공급자 항목은 문서상 지원 표시가 없습니다.
Pi: 스킬은 지원하지만 Pi 자체에 MCP 클라이언트가 없어 MCP 서버 항목은 지원되지 않습니다.
데스크톱·IDE: CLI와 데스크톱, IDE 지원이 다르며 일부 표면은 별도 수동 설정 또는 향후 지원으로 표시됩니다.

따라서 “한 번 게시하면 모든 도구가 완전히 같아진다”고 이해하면 안 됩니다. 먼저 팀이 실제로 쓰는 에이전트와 버전을 정하고, 모델·MCP·스킬·추적 중 필요한 기능이 각 표면에서 지원되는지 표로 확인해야 합니다.

실용적인 적용 예시 3가지

1. Codex와 Claude Code에 같은 GitHub 도구 정책 적용

목적은 두 에이전트가 서로 다른 개인 설정을 쓰지 않고, 승인된 GitHub MCP 서버만 사용하도록 만드는 것입니다. 관리자는 Unity Catalog에 등록된 서버와 읽기·쓰기 권한을 준비하고 관리형 구성에 포함합니다. 개발자는 ug configure 또는 다음 실행에서 구성을 동기화한 뒤 ug codex, ug claude로 시작합니다. 완료 기준은 두 에이전트의 MCP 상태에서 같은 서버가 연결되고, 권한 밖 저장소나 변경 작업이 차단되는지 확인하는 것입니다.

2. 코드 리뷰 스킬을 프로젝트 단위로 배포

목적은 리뷰 체크리스트를 채팅 프롬프트로 매번 복사하지 않고 버전 관리하는 것입니다. 스킬을 Unity Catalog에 게시하고 테스트 프로젝트에서 ug skills add --path "$PWD"로 내려받습니다. 산출물은 프로젝트의 스킬 폴더와 리뷰 결과이며, 검토 기준은 보안·테스트·마이그레이션 같은 필수 항목이 빠지지 않는지입니다. 스킬은 권한을 대신하지 않으므로 파일 수정과 명령 실행 정책은 별도로 유지해야 합니다.

3. 반복 실패하는 MCP 호출 찾기

목적은 모델 성능을 막연히 의심하기 전에 실패가 도구, 권한, 입력 크기, 재시도 설계 중 어디에서 생기는지 찾는 것입니다. 관리자는 통합 추적을 활성화하고 전용 Unity Catalog 테이블에 기록되도록 구성합니다. 이후 서비스명, 상태 코드, 사용자, 시간 범위로 오류를 좁힙니다. 다만 추적 전달은 best-effort이고 일부 오류 로그가 보장되지 않으므로, 규정 준수의 유일한 기록으로 쓰지 말고 Databricks 감사 로그와 함께 봐야 합니다.

비용 관리와 추적에서 주의할 점

ug usage는 현재 사용액, 전체 예산, 사용 비율을 보여줍니다. 하지만 개발자가 이 정보를 보려면 관리형 구성에 적절한 예산 ID가 연결되고, 계정 차원의 Preview와 사용자별 차단 임계값이 설정돼 있어야 합니다. 명령이 존재한다고 모든 워크스페이스에서 곧바로 예산이 표시되는 것은 아닙니다.

통합 추적 테이블은 요청·응답과 도구 활동을 한곳에서 분석하는 데 유용하지만 민감한 프롬프트와 페이로드를 포함할 수 있습니다. 기본 조회 권한이 메타스토어 관리자에게만 주어지는 이유입니다. 다른 팀에 열 때는 Unity Catalog 권한과 행 필터 정책을 먼저 설계해야 합니다. 로그 전달 지연, 일부 상태 코드 누락 가능성, 3MiB를 넘는 속성의 잘림, 보존 정책을 직접 정해야 하는 제한도 있습니다.

로컬 에이전트의 파일·셸 권한은 게이트웨이만으로 모두 해결되지 않습니다. 모델과 MCP 트래픽을 중앙 통제해도 에이전트가 로컬 작업 폴더에서 무엇을 읽고 쓸 수 있는지는 해당 에이전트의 샌드박스와 승인 정책에 달려 있습니다. 프로젝트별 격리가 필요하다면 GitHub Copilot 앱 로컬 샌드박스 설정 가이드처럼 로컬 실행 경계도 함께 검토해야 합니다.

문제가 생겼을 때 확인 순서

ug --version으로 설치와 실행 경로를 확인합니다.
ug status로 워크스페이스, 생성 파일, 모델, 스킬 MCP 범위를 확인합니다.
ug doctor로 로컬 에이전트 설정 오류와 수정 제안을 확인합니다.
인증이나 모델 목록이 오래됐다면 Codex·Claude 실행에 --refresh를 붙이거나 ug configure를 다시 실행합니다.
MCP 문제는 ug mcp list에서 에이전트별 연결 상태를 확인하고, 서버 뒤의 실제 데이터 권한을 별도로 점검합니다.
관리형 구성이 갱신되지 않으면 Preview 활성화, 게시된 구성, 사용자의 모델 EXECUTE 권한을 관리자에게 확인합니다.
변경 전 상태로 돌아가야 하면 활성 작업을 끝낸 뒤 ug revert로 백업된 설정 복원을 검토합니다.

누구에게 적합한가

Unity Gateway CLI는 개인 개발자가 Codex나 Claude Code를 처음 써보기 위한 가장 가벼운 설치법은 아닙니다. Databricks 워크스페이스와 Unity Catalog를 이미 사용하고 있으며, 여러 팀의 모델 접근·MCP·스킬·비용·추적 정책을 한곳에서 운영하려는 조직에 맞습니다. 반대로 에이전트 한 개를 개인 프로젝트에서 쓰거나 중앙 관리가 필요 없다면 각 도구의 기본 인증과 로컬 설정이 더 단순할 수 있습니다.

도입할 때는 모든 에이전트를 한꺼번에 연결하기보다 읽기 전용 MCP 한 개, 모델 한두 개, 테스트 프로젝트 하나로 시작하는 편이 안전합니다. 설치 성공보다 중요한 완료 기준은 승인된 자원만 보이는지, 설정 변경을 되돌릴 수 있는지, 로그를 볼 사람과 보존 기간이 정해졌는지입니다.

공식 자료

자료 확인일: 2026년 9월 30일. Beta·Preview 범위와 지원 에이전트는 이후 변경될 수 있으므로 실제 적용 전 최신 공식 문서를 확인하세요.

Read this guide in English

이 블로그 검색

스택핀치