Cloudera AI Workbench MCP Server

Cloudera Agent Studio가 uvx로 실행하는 로컬 Python MCP 서버입니다. MCP 통신은 stdio만 사용하고, 서버 프로세스가 인증된 Cloudera AI Workbench API v2를 직접 호출합니다. 별도의 원격 MCP HTTP 서버는 운영하지 않습니다.

이 서버는 API 목록을 그대로 노출하지 않습니다. Agent가 실제 운영 질문과 작업을 처리할 수 있도록 여러 API 호출·이름 해석·집계를 묶은 업무형 tool을 제공합니다.

에이전트의 tool 선택, 이름 해석, 실행 안전 정책은 AGENT_GUIDE.md를 참고하십시오.

기술 기준

• Python 3.11 이상
• 공식 MCP Python SDK v2
• mcp>=2.0.0,<3
• MCP transport: stdio
• REST client: httpx.AsyncClient
• API prefix: 코드에 고정된 /api/v2

stdout은 MCP wire message 전용이며 애플리케이션 로그는 stderr로 출력됩니다. API path나 HTTP method를 모델 입력으로 받는 범용 호출 도구는 없습니다.

제공 tool과 API 매핑

패키지는 권한 경계에 따라 세 MCP entry point를 제공합니다.

MCP entry point	목적	현재 공개 tool
cai-workbench-insights	조회·분석	overview, workload·Application 상세·Model·Deployment 검색, 리소스, job 상태
cai-workbench-operations	실행·중지·수정	job 실행·중지, Application 재시작·종료·수정, Model Deployment 재시작
cai-workbench-admin	관리자 조회·권한 관리	Runtime·사용자 quota·프로젝트 권한

세 서버를 한 패키지에서 설치하되 Agent Studio에서는 필요한 서버만 연결합니다. Operations는 CAI_ENABLE_JOB_RUNS=false가 기본이며, Admin은 일반 사용자 에이전트와 분리해 연결합니다.

MCP tool	역할	내부 Workbench API v2
get_workbench_overview	최근 workload 상태·실패·현재 실행 중 workload·자원 합계 요약	GET /usage
find_workloads	이름, 시간, 상태, 프로젝트, 유형, 생성자로 workload 검색	GET /usage
get_current_resource_usage	현재 workload의 CPU·메모리·GPU 값을 전체/프로젝트/유형별 집계	GET /usage
get_project_operations_summary	프로젝트의 workload·Application·Model·Job·리소스 운영 상태 요약	GET /usage, GET .../applications, GET .../models, GET /jobs
list_applications	프로젝트의 Application 상태·리소스 조회	GET /projects, GET .../applications
get_application_details	특정 Application의 안전한 상세 메타데이터 조회	GET .../applications, GET .../applications/{application_id}
list_models	프로젝트의 Model 목록·메타데이터 조회	GET /projects, GET .../models
get_model_details	Model 설명·인증·기본 리소스·replica 설정 조회	GET /projects, GET .../models
list_model_deployments	프로젝트 Model Deployment 상태 조회	GET .../models, GET .../builds, GET .../deployments
get_job_status	job 이름을 전체 접근 가능 job에서 찾아 최근 run 상태 조회	내부 GET /jobs, GET .../runs
get_job_details	job의 설명·스케줄·일시정지·리소스 설정 조회	GET /jobs, GET /projects/{project_id}/jobs/{job_id}
get_job_run_history	최근 Job 실행 상태·시각·소요 시간·실패 사유 조회	GET /jobs, GET .../runs
run_job	허용 목록의 job 이름을 안전하게 해석하여 새 run 시작	내부 GET /jobs, POST .../runs
rerun_failed_job	최신 실패 Job을 중복 실행 없이 재실행	GET /jobs, GET .../runs, POST .../runs
stop_job_run	프로젝트와 job 이름으로 현재 실행 중인 run을 찾아 중지	내부 GET /jobs, GET .../runs, POST .../runs/{run_id}:stop
update_job	job 설명·cron 스케줄·일시정지 상태 수정	GET /jobs, GET .../jobs/{job_id}, PATCH .../jobs/{job_id}
restart_application	프로젝트의 실패 Application을 이름으로 찾아 재시작	GET /projects, GET .../applications, POST .../applications/{application_id}:restart
stop_application	실행 중 Application을 확인 후 종료	GET /projects, GET .../applications, POST .../applications/{application_id}:stop
update_application	Application 설명·리소스·인증·환경변수 수정	GET .../applications, PATCH .../applications/{application_id}
restart_model_deployment	실패한 Model Deployment를 찾아 재시작	GET .../models, GET .../builds, GET .../deployments, POST ...:restart
update_model	Model 설명·인증·기본 CPU·메모리·GPU·replica 수정	GET /projects, GET .../models, PATCH .../models/{model_id}
list_runtimes	kernel/editor/edition 조건으로 Runtime 조회	GET /runtimes
list_users_quota	사용자별 자원 quota 조회	GET /usersquota
list_project_collaborators	프로젝트 사용자·권한 조회	GET /projects/{project_id}/collaborators
get_project_details	프로젝트 설정·권한·환경변수 키 조회	GET /projects/{project_id}
update_project	프로젝트 설명·Runtime·리소스·환경변수 수정	PATCH /projects/{project_id}
set_project_collaborator	프로젝트 사용자 추가 또는 권한 변경	PUT /projects/{project_id}/collaborators/{username}
remove_project_collaborator	프로젝트 사용자 제거	DELETE /projects/{project_id}/collaborators/{username}

get_current_resource_usage 결과는 /api/v2/usage가 현재 각 workload에 보고한 CPU, memory, GPU 수치의 합계입니다. 사용률 퍼센트나 과거 시간 구간의 누적 소비량으로 해석하면 안 되며, 응답의 metric_semantics에도 이 제한을 표시합니다.

get_workbench_overview도 /api/v2/usage만 사용합니다. /api/v2/workloads/executions는 Cloudera Observability machine user로 구성된 환경에서만 접근 가능한 경우가 있어 기본 Workload 사용자 인증으로는 호출하지 않습니다. 따라서 overview의 execution_summary와 recent_failures는 usage 응답의 상태/생성 시각을 기준으로 계산됩니다. 최신 실패 항목은 최대 3개만 반환합니다.

job 목록은 공개 tool이 아닙니다. get_job_status와 run_job이 사람이 입력한 이름을 API ID로 변환할 때만 내부에서 사용합니다. project_id, job_id, page token과 API filter JSON은 어떤 MCP tool도 입력받지 않습니다.

Tool 파라미터

Tool	필수 입력	Optional 입력과 기본값
get_workbench_overview	없음	window_hours=24 (1~168)
find_workloads	없음	query=null, project_name=null, status=null, workload_type=null, creator=null, lookback_hours=null, max_results=20
get_current_resource_usage	없음	project_name=null, workload_type=null, status="running"
get_project_operations_summary	project_name	없음
list_applications	project_name	application_name=null, status=null, max_results=20
get_application_details	project_name, application_name	없음
list_models	project_name	model_name=null, max_results=20
get_model_details	project_name, model_name	없음
list_model_deployments	project_name	model_name=null, deployment_name=null, status=null, max_results=20
get_job_status	없음 (단, job_name과 project_name 중 하나는 필요)	job_name=null, project_name=null, recent_runs=5
get_job_details	job_name	project_name=null
get_job_run_history	job_name	project_name=null, recent_runs=3 (1~20)
run_job	job_name	project_name=null
rerun_failed_job	job_name, project_name	confirm=false
stop_job_run	job_name, project_name	없음 (중지 대상 run은 서버가 현재 상태에서 해석)
update_job	job_name, project_name	description=null, schedule=null, paused=null, confirm=false
restart_application	project_name	application_name=null (생략 시 실패 후보 검색)
stop_application	project_name	application_name=null, confirm=false
update_application	project_name, application_name	수정 필드 선택, set_environment=null, remove_environment=null, confirm=false
restart_model_deployment	project_name	model_name=null, deployment_name=null, confirm=false
update_model	project_name, model_name	수정 필드 선택, confirm=false
list_runtimes	없음	kernel=null, editor=null, edition=null, page_size=100
list_users_quota	없음	username=null, page_size=100
list_project_collaborators	project_name	username=null, permission=null, max_results=50
get_project_details	project_name	없음
update_project	project_name	수정 필드 선택, confirm=false
set_project_collaborator	project_name, username, permission	confirm=false
remove_project_collaborator	project_name, username	confirm=false

stop_job_run은 현재 실행 중인 run이 정확히 하나일 때만 중지합니다. 여러 run이 동시에 실행 중이면 임의로 선택하지 않고 후보 시각을 반환하며, 아무 것도 중지하지 않습니다.

list_users_quota의 username은 공식 API query filter가 아니므로 MCP가 모든 페이지를 조회한 뒤 응답을 로컬 필터링합니다. API가 지원하지 않는 username 검색 조건은 upstream에 전달하지 않습니다.

find_workloads의 lookback_hours는 workload 생성 시각 필터입니다. 생략하면 시간 필터를 적용하지 않으므로 오래 실행 중인 workload도 상태 검색에서 누락되지 않습니다. status와 workload_type은 서버가 Workbench의 /workloadstatus, /workloadtypes 목록과 대소문자 무시 방식으로 검증하며, 잘못된 값이면 현재 사용할 수 있는 값을 반환합니다.

get_job_status는 전체 접근 가능 job을 이름으로 검색합니다. job_name을 생략하고 project_name만 지정하면 해당 프로젝트의 job 목록과 각 최신 run 상태를 반환합니다. 두 값을 모두 생략하면 검색 범위가 모호하므로 오류를 반환합니다. project_name을 생략해도 job 이름이 유일하면 자동으로 프로젝트를 찾습니다. 동일 이름이 여러 프로젝트에 있으면 ID가 아닌 프로젝트명 후보를 반환하므로 Agent가 사용자에게 선택을 요청할 수 있습니다. 조회는 유일한 대소문자 무시 일치도 허용하지만 임의의 부분 일치를 선택하지 않습니다.

get_job_details는 job 이름을 사람이 입력하는 방식으로 해석한 뒤 설명, cron schedule, paused 상태, 리소스와 Runtime 설정을 반환합니다. 환경변수 값은 반환하지 않고 키 이름만 표시합니다. update_job은 description, schedule, paused만 수정할 수 있으며, 항상 confirm=false 미리보기를 먼저 반환합니다. 사용자가 변경 대상과 cron 표현식을 확인한 뒤 같은 인자로 confirm=true를 호출해야 PATCH가 실행됩니다. 미리보기에는 cron 문법 검증 결과와 다음 실행 예정 시각(UTC)이 포함되며, 잘못된 표현식이면 PATCH하지 않습니다. 스케줄을 끄려면 cron 값을 임의로 비우지 말고 paused=true를 사용합니다.

인증 및 환경변수

CAI_BASE_URL에는 Workbench 도메인만 입력합니다. CAI_TOKEN은 Workbench에서 audience=API로 생성한 API Key여야 합니다. CAI_TOKEN을 생략하면 Workbench 세션에서 제공되는 CDSW_APIV2_KEY를 자동으로 fallback으로 사용합니다. AI Inference workload의 /tmp/jwt는 이 API의 자격증명이 아니므로 사용하지 않습니다.

이름	필수	기본값	설명
CAI_BASE_URL	예	없음	Workbench origin. 예: https://ml-xxxx.example.com
CAI_TOKEN	예*	없음	Workbench API v2 Bearer API Key (audience=API)
CDSW_APIV2_KEY	fallback	없음	CAI_TOKEN이 없을 때 사용할 Workbench 세션 API v2 Key
CAI_ENABLE_JOB_RUNS	아니요	false	run_job 기능의 운영자 전역 스위치
CAI_ALLOWED_JOBS	실행 시	[]	정확한 project/job 쌍의 JSON 배열 또는 comma 목록
CAI_MAX_RECORDS	아니요	100	내부 API 한 번에 읽는 최대 record 수(1~500)
CAI_TIMEOUT_SECONDS	아니요	30	REST timeout(초)
CAI_VERIFY_TLS	아니요	true	TLS 인증서 검증
CAI_LOG_LEVEL	아니요	INFO	DEBUG, INFO, WARNING, ERROR, CRITICAL

* CAI_TOKEN이 없으면 CDSW_APIV2_KEY가 자동 사용됩니다.

운영 환경에서는 CAI_VERIFY_TLS=true를 유지하십시오. CAI_TOKEN은 로그와 tool 결과에 출력하지 않습니다.

run_job 안전 정책

run_job은 MCP annotation에서 destructive/non-idempotent tool로 선언되어 있고, 다음 두 조건을 모두 만족해야 실행됩니다.

CAI_ENABLE_JOB_RUNS=true
CAI_ALLOWED_JOBS=["Fraud Detection/Nightly Train","Forecast/Daily Refresh"]

job_name은 일반 실행 요청에서 필요합니다. 정확히 일치하는 허용 Job이 없으면 서버가 허용 목록에 해당하는 유사 후보를 반환하며 실행하지 않습니다. project_name을 생략했을 때 allowlist에 같은 job 이름이 정확히 하나면 프로젝트를 자동 선택합니다. 둘 이상의 프로젝트에 같은 job 이름이 등록되어 있을 때만 project_name을 요구합니다. 실행 시에는 대소문자를 포함한 정확한 allowlist 일치만 허용하고 부분 일치나 추정은 하지 않습니다.

confirm=true 같은 모델 입력을 보안 경계로 사용하지 않습니다. 재시도하면 새 run이 중복 생성될 수 있으므로 POST 요청은 자동 재시도하지 않습니다. 초기 버전은 임의 환경변수나 실행 인자도 모델에게 받지 않습니다.

로컬 개발과 테스트

uv를 설치한 뒤 다음을 실행합니다.

cp .env.example .env
# .env의 Workbench URL과 API Key를 수정

uv sync --all-extras
uv run ruff check .
uv run pytest

MCP Inspector로 tool schema를 확인할 수 있습니다.

uv run --env-file .env mcp dev src/cai_mcp_server/server.py:mcp --with-editable .

서버 자체는 stdio peer가 연결해야 하므로 실행 중 터미널에 문자를 직접 입력하지 마십시오.

uv run --env-file .env cai-mcp-server

wheel 및 uvx 검증

uv build
  uvx --from ./dist/cai_mcp_server-0.2.1-py3-none-any.whl cai-mcp-server

개발 중에는 현재 소스를 바로 설치할 수도 있습니다.

uvx --from . cai-mcp-server

패키지 저장소에 배포한 뒤 Agent Studio에는 다음 형태로 등록합니다.

{
  "command": "uvx",
  "args": [
    "--from",
    "cai-mcp-server==0.2.1",
    "cai-mcp-server"
  ]
}

Agent Studio는 한 번에 MCP 서버 하나만 등록할 수 있습니다. 다음 파일을 각각 별도로 가져오세요.

• agent-studio-insights.json
• agent-studio-operations.json
• agent-studio-admin.json

각 JSON을 하나씩 등록하고 CAI_BASE_URL과 CAI_TOKEN을 실제 값으로 교체합니다. private package index를 사용한다면 Agent Studio runtime에서 접근 가능한 uv/Python index도 구성해야 합니다.

테스트 범위와 live 검증

자동 테스트는 다음을 검증합니다.

• 필수 API Key, 실행 스위치, 정확한 job allowlist parsing
• 공식 API v2 path, JSON query filter, Bearer header, POST body
• API 응답 정규화, 실행/현재 자원 집계, 동적 status/type 검증
• project 이름 생략, 중복 후보 반환, 읽기용 대소문자 무시 해석
• 실행용 exact allowlist와 유일한 allowlisted project 추론
• upstream 오류의 민감 정보 제거
• 각 컴포넌트에 의도한 tool만 노출되는지와 tool 호출 성공/차단
• 모든 공개 tool input에서 project_id, job_id가 제외되는지
• 실제 subprocess의 stdio MCP initialize 및 tool 목록 조회

Workbench 배포 버전에 따라 인스턴스의 정확한 계약은 https://<workbench-domain>/api/v2/swagger.json에서 확인할 수 있습니다. 실제 endpoint를 사용한 live 검증은 유효한 CAI_BASE_URL과 CAI_TOKEN이 있을 때 별도로 수행하십시오.

관련 공식 문서:

• Cloudera AI Workbench API v2 시작 안내
• Cloudera AI API v2 REST reference
• Agent Studio MCP server 등록 get_job_run_history는 최근 실행의 메타데이터만 반환합니다. 이 Workbench API 구성에서는 실행 로그·스택트레이스를 제공하지 않으므로 로그가 있다고 추정하거나 생성하지 않습니다.