AI Builder App 배포 핸즈온 - Databricks 가이드

소요 시간: ~5분 | 핵심: AI Dev Kit Builder App을 MCP 서버와 함께 배포하기 간편 배포: 아래 수동 과정 대신 Genie Code에 AI Dev Kit 구성하기의 deploy.sh --enable-mcp를 사용하면 한 줄로 완료됩니다. 이 페이지는 수동 설정이 필요할 때 참조하세요.

이 모듈에서 사용하는 Databricks 기능

기능	설명	공식 문서
Databricks Apps	Databricks 워크스페이스 안에서 웹 애플리케이션(FastAPI, Streamlit 등)을 배포·관리하는 플랫폼입니다. 앱마다 서비스 프린시펄(Service Principal)이 자동 생성되어 권한 관리가 됩니다.	docs
MCP (Model Context Protocol)	AI 도구가 외부 시스템과 통신하는 표준 프로토콜입니다. MCP 서버를 앱으로 배포하면 Genie Code에서 추가 도구를 사용할 수 있습니다.	spec
Service Principal	사람이 아닌 앱/자동화 프로세스 전용 계정입니다. 앱이 API를 호출할 때 이 계정의 권한으로 동작합니다.	docs
Databricks CLI	터미널에서 Databricks 리소스를 관리하는 명령줄 도구입니다.	docs

개요

AI Dev Kit의 Builder App을 --enable-mcp 옵션으로 배포하면, 한 앱에서 두 가지 기능을 동시에 제공합니다:

Builder 웹 UI — 브라우저에서 Vibe Coding으로 앱 빌드
MCP 서버 (/mcp) — Genie Code에서 75+ 도구 사용

┌────────────────────────────────────────────┐
│   Builder App (mcp-builder-app)            │
│                                             │
│   브라우저 접속 → Builder 웹 UI              │
│   Genie Code 연결 → MCP 서버 (/mcp)         │
└────────────────────────────────────────────┘

간편 배포 (권장)

# AI Dev Kit 클론
git clone https://github.com/databricks-solutions/ai-dev-kit.git
cd ai-dev-kit/databricks-builder-app

# Builder App + MCP 서버 배포
./scripts/deploy.sh mcp-builder-app --enable-mcp --profile <PROFILE>

중요: 앱 이름은 반드시 mcp-로 시작해야 Genie Code에서 MCP 서버로 인식됩니다.

deploy.sh가 자동으로 처리:

앱 생성 + 소스 코드 업로드 + 배포
서비스 프린시펄 권한 부여
Skills 배포 (Genie Code 자동 로딩)
MCP 엔드포인트 활성화 (/mcp)

수동 배포 (deploy.sh가 안 될 때)

Step 1: 사전 준비

# CLI 설치 확인
databricks --version

# 인증
databricks auth login --host https://<your-workspace-url>
databricks current-user me

Step 2: 레포 클론

git clone https://github.com/databricks-solutions/ai-dev-kit.git
cd ai-dev-kit

Step 3: 앱 생성

databricks apps create mcp-builder-app \
  --description "AI Dev Kit Builder App with MCP"

Step 4: 소스 코드 업로드 & 배포

DBUSER=$(databricks current-user me | jq -r .userName)
APP_PATH="/Workspace/Users/$DBUSER/mcp-builder-app"

databricks workspace mkdirs "$APP_PATH"

# Builder App 소스 업로드
for f in databricks-builder-app/app/*; do
  [ -f "$f" ] || continue
  databricks workspace import "$APP_PATH/$(basename $f)" \
    --file "$f" --format RAW --overwrite
done

# 배포
databricks apps deploy mcp-builder-app --source-code-path "$APP_PATH"
databricks apps get mcp-builder-app

Step 5: 서비스 프린시펄 권한 부여

# SP 정보 확인
SP_CLIENT_ID=$(databricks apps get mcp-builder-app -o json | jq -r .service_principal_client_id)
SP_ID=$(databricks apps get mcp-builder-app -o json | jq -r .service_principal_id)

# 엔타이틀먼트 부여
databricks api patch /api/2.0/preview/scim/v2/ServicePrincipals/$SP_ID --json '{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{"op": "add", "value": {
    "entitlements": [
      {"value": "allow-cluster-create"},
      {"value": "workspace-access"},
      {"value": "databricks-sql-access"}
    ]
  }}]
}'

-- 카탈로그 권한 (노트북에서 실행)
GRANT ALL PRIVILEGES ON CATALOG lge_smart_tv TO `<sp_client_id>`;

# SQL Warehouse 권한
WH_ID="<your_warehouse_id>"
TOKEN=$(databricks auth token | jq -r .access_token)
HOST=$(databricks auth env | jq -r .env.DATABRICKS_HOST)

curl -X PATCH "$HOST/api/2.0/permissions/warehouses/$WH_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"access_control_list\": [{
    \"service_principal_name\": \"$SP_CLIENT_ID\",
    \"permission_level\": \"CAN_USE\"
  }]}"

Step 6: Skills 배포

# Skills를 Workspace에 업로드
TARGET="/Workspace/.assistant/skills"
for skill_dir in databricks-skills/*/; do
  skill_name=$(basename "$skill_dir")
  [ "$skill_name" = "TEMPLATE" ] && continue
  databricks workspace mkdirs "$TARGET/$skill_name"
  for f in "$skill_dir"*; do
    [ -f "$f" ] || continue
    databricks workspace import "$TARGET/$skill_name/$(basename $f)" \
      --file "$f" --format RAW --overwrite
  done
  echo "✓ $skill_name"
done

Skills는 /Workspace/.assistant/skills/에 업로드하면 Genie Code가 자동으로 로딩합니다.

배포 확인

# 앱 상태 확인
databricks apps get mcp-builder-app

# 앱 URL 확인 (Builder 웹 UI)
databricks apps get mcp-builder-app -o json | jq -r .url

앱이 RUNNING 상태이면 성공입니다!

Genie Code 연결

배포 완료 후 **Section 3: Genie Code에 AI Dev Kit 구성하기**의 Step 3~5를 따라 Genie Code에서 MCP 서버를 연결하고 도구를 선택합니다.

트러블슈팅

문제	원인	해결
앱 상태 `FAILED`	의존성 오류	`databricks apps logs mcp-builder-app`로 로그 확인
Genie Code에서 안 보임	앱 이름이 `mcp-`로 시작 안 함	앱 삭제 후 `mcp-` 접두사로 재생성
권한 오류	서비스 프린시펄 권한 부족	Step 5 재실행
도구가 20개 초과	MCP 도구 제한	Settings에서 필요한 도구만 ON
MCP 도구 타임아웃	앱이 유휴 상태	`databricks apps stop mcp-builder-app && databricks apps start mcp-builder-app`

다음 단계

Section 3: Genie Code + AI Dev Kit 연결 — MCP 서버를 Genie Code에 연결하고 도구 선택/테스트

​이 모듈에서 사용하는 Databricks 기능

​개요

​간편 배포 (권장)

​수동 배포 (deploy.sh가 안 될 때)

​Step 1: 사전 준비

​Step 2: 레포 클론

​Step 3: 앱 생성

​Step 4: 소스 코드 업로드 & 배포

​Step 5: 서비스 프린시펄 권한 부여

​Step 6: Skills 배포

​배포 확인

​Genie Code 연결

​트러블슈팅

​다음 단계