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를 제공합니다.

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

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의 window_activity_summary와 recent_failures는 지정된 조회 구간에 생성된 usage 응답을 기준으로 계산됩니다. current_running_summary와 current_running_workloads는 생성 시각과 관계없이 현재 running 상태로 보고된 항목을 나타냅니다. 최신 실패 항목은 최대 3개만 반환합니다.

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

Tool 파라미터

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

list_users_quota의 username은 공식 API query filter가 아니므로 MCP가 user_quota 전체 페이지를 조회한 뒤 user.user_name을 정확히 비교합니다. 결과는 사용자명과 설정 quota, 현재 사용량만 포함하는 일관된 형태로 반환합니다.

find_latest_workload_statuses는 /usage가 반환한 레코드를 프로젝트·유형·이름·생성자 조합으로 묶어 가장 최근 레코드만 남긴 뒤 final_status를 적용합니다. 따라서 과거에 실패했지만 현재 최신 레코드가 running인 workload는 실패 결과에 포함되지 않습니다. 이름 충돌이 잦고 안정적인 식별자가 없는 session 레코드는 임의로 합치지 않습니다.

search_workload_history는 레코드를 합치지 않는 과거 활동 검색입니다. lookback_hours는 workload 생성 시각 필터이며 생략하면 시간 필터를 적용하지 않습니다. 두 tool의 status/final_status와 workload_type은 Workbench의 /workloadstatus, /workloadtypes 목록으로 검증합니다. 두 결과 모두 /usage 관측값이며 Application 목록이나 실행 로그가 아닙니다. 실제 존재하는 Application 목록은 list_applications를 사용합니다.

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_API_KEY는 Workbench에서 발급한 API Key입니다. CAI_API_KEY를 생략하면 Workbench 세션에서 제공되는 API Key를 사용합니다. AI Inference workload의 /tmp/jwt는 이 API의 자격증명이 아니므로 사용하지 않습니다.

* API Key가 없으면 도구 목록은 표시되지만 API 호출은 인증 오류를 반환합니다.

운영 환경에서는 CAI_VERIFY_TLS=true를 유지하십시오. API Key는 로그와 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.10",
    "cai-mcp-server"
  ]
}

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

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

각 JSON을 하나씩 등록하고 CAI_BASE_URL과 CAI_API_KEY를 실제 값으로 교체합니다. 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_API_KEY가 있을 때 별도로 수행하십시오.

관련 공식 문서:

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