MCP Reference: cloudcli.googleapis.com

Cloud CLI MCP 서버는 원격 샌드박스 환경에서 Cloud CLI 명령어를 실행하는 도구를 제공합니다.

모델 컨텍스트 프로토콜 (MCP) 서버는 대규모 언어 모델 (LLM) 또는 AI 애플리케이션에 컨텍스트, 데이터 또는 기능을 제공하는 외부 서비스 간의 프록시 역할을 합니다. MCP 서버는 AI 애플리케이션을 데이터베이스 및 웹 서비스와 같은 외부 시스템에 연결하여 AI 애플리케이션이 이해할 수 있는 형식으로 응답을 변환합니다.

서버 설정

사용하기 전에 MCP 서버를 사용 설정하고 인증을 설정해야 합니다. Google 및 Google Cloud 원격 MCP 서버 사용에 대한 자세한 내용은 Google Cloud MCP 서버 개요를 참고하세요.

서버 엔드포인트

MCP 서비스 엔드포인트는 AI 애플리케이션 (MCP 클라이언트의 호스트)이 보안 표준 연결을 설정하는 데 사용하는 MCP 서버의 네트워크 주소 및 통신 인터페이스 (일반적으로 URL)입니다. LLM이 컨텍스트를 요청하거나, 도구를 호출하거나, 리소스에 액세스할 때 사용하는 연락처입니다. Google MCP 엔드포인트는 전역 또는 리전일 수 있습니다.

Cloud CLI 실행 API MCP 서버에는 다음과 같은 전역 MCP 엔드포인트가 있습니다.

  • https://cloudcli.googleapis.com/mcp

MCP 도구

MCP 도구는 MCP 서버가 현실 세계에서 작업을 실행하기 위해 LLM 또는 AI 애플리케이션에 노출하는 함수 또는 실행 가능한 기능입니다.

도구

cloudcli.googleapis.com MCP 서버에는 다음 도구가 있습니다.

MCP 도구
run_gcloud_command

사용자의 Google Cloud 프로젝트 내에서 단일 gcloud CLI 명령어를 실행합니다. 심각한 안전 경고 (잠재적으로 파괴적): 이 도구는 GCP 리소스 (예: gcloud compute instances delete)를 만들거나 업데이트하거나 삭제할 수 있습니다. 읽기 전용 명령어로 제한되지 않습니다. 각별히 주의하세요. 금지된 명령어: 에이전트는 다음 gcloud 명령어(알파/베타 변형 포함)를 실행하면 안 됩니다(MUST NOT). app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey 엄격한 실행 규칙:

  1. 이 도구를 사용할 때는 'project' 매개변수(예: project="projects/PROJECT_ID")를 제공해야 합니다(Cloud CLI Execution API 사용 설정 확인, 결제, 할당량 등에 사용됨)(MUST). 이는 gcloud가 작동하는 프로젝트를 지정하는 데 사용되는 gcloud 명령어의 --project 플래그와는 다릅니다.
  2. 플래그 형식: 모든 긴 옵션에 대해 플래그 키와 값을 구분할 때는 항상 '=' 기호를 사용해야 합니다(MUST). 올바른 값: --zone=us-central1-a 또는 --project=my-project. 잘못됨: --zone us-central1-a 또는 --project my-project.
  3. 결제 프로젝트: 실행 환경에서 사전 구성된 프로젝트 또는 결제 설정을 가정할 수 없습니다. 프로젝트 범위가 아닌 명령어(예: 폴더 또는 조직 수준) 또는 Cloud Storage 요청자 지불과 같은 특정 시나리오의 경우 --billing-project=PROJECT 플래그를 전달해야 합니다(MUST). 프로젝트 범위 명령어의 경우 할당량 프로젝트를 재정의하기 위해 --billing-project=PROJECT를 추가로 지정할 수 있습니다(MAY). 이는 리소스-프로젝트-재정의를 지원하지 않는 GCP API에 적용됩니다.
  4. 프로젝트 범위: 프로젝트 범위 명령어에는 항상 --project=PROJECT_ID 플래그를 전달해야 합니다(SHOULD). 조직 또는 폴더 수준 명령어에는 사용하지 마세요. 프로젝트 범위 명령어에 --project 플래그를 제공하지 않으면 리소스 프로젝트가 --billing-project 플래그에 설정된 프로젝트로 기본 설정됩니다.
  5. gcloud 명령어에서 --billing-project 플래그를 지정하는 경우 값이 프로젝트 ID 또는 프로젝트 번호인지 확인합니다. 값은 특수 값(예: LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK)이 아니어야 합니다(MUST NOT).
  6. 명령어 문자열에 --project 또는 --billing-project 중 하나 이상을 지정해야 합니다(MUST).
  7. 비동기 작업: 장기 실행 동기 작업(예: VM 또는 데이터베이스 생성)의 경우 에이전트 시간 초과를 방지하기 위해 항상 --async 플래그를 전달해야 합니다(SHOULD).
  8. 로그 비율 제한: gcloud logging read를 사용할 때는 항상 --limit 플래그(예: --limit=100)를 포함하여 사용자 인증 정보 및 연결 시간 초과를 방지해야 합니다(MUST).
  9. 자가 수정: 명령어가 오류를 반환하면 stderr를 분석하고, 문법이나 플래그를 수정하고, 다음 반복에서 다시 시도합니다.
  10. input_files: (선택사항) 명령어를 실행하기 전에 환경에 생성할 파일 목록입니다. 각 파일에는 '경로' (현재 디렉터리 기준)와 '콘텐츠'가 있어야 합니다. 'contents'는 파일의 콘텐츠를 나타내는 일반 텍스트여야 합니다. 이는 파일에서 읽어오는 명령어 (예: gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID)에 유용합니다.

gcloud 명령어/패턴 예시:

  1. 심각도가 ERROR 이상인 GCE 인스턴스 로그를 읽습니다. gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • 필터 표현식에 따옴표가 사용된 것을 확인하세요.
  2. 모든 PSC 엔드포인트를 나열합니다. gcloud compute forwarding-rules list --project=PROJECT_ID
  3. PSC 엔드포인트를 설명합니다. gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • --region 플래그에 '='가 사용된 것을 확인하세요.
  4. 모든 클러스터 나열: gcloud container clusters list --project=PROJECT_ID
  5. 클러스터 설명: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. 컴퓨팅 인스턴스 나열: gcloud compute instances list --project=PROJECT_ID
  7. 프로젝트의 IAM 정책 가져오기: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

응답 문자열은 기본적으로 터미널 출력 (stdout 또는 stderr)용으로 형식이 지정됩니다. --format 플래그를 사용하여 형식을 변경합니다.
run_bq_command

단일 BigQuery CLI (bq) 명령어를 실행합니다. 이 도구를 사용하면 GCP 리소스 (즉, 변형)를 생성, 업데이트 또는 삭제하는 명령어를 비롯하여 사용자의 프로젝트에서 모든 bq 명령어를 실행할 수 있습니다. 심각한 안전 경고 (파괴적일 수 있음): 이 도구는 BigQuery 리소스 (예: bq rm, bq cancel, bq query)를 만들거나 업데이트하거나 삭제할 수 있습니다. 읽기 전용 명령어로 제한되지 않습니다. 각별히 주의하세요. 금지된 명령어: 에이전트는 bq init, bq load, bq pyshell, bq shell bq 명령어를 실행해서는 안 됩니다(MUST NOT). 엄격한 실행 규칙:

  1. 명령어 문자열에 --project_id 또는 --quota_project_id 중 하나 이상을 지정해야 합니다(MUST).
  2. 프로젝트 ID와 할당량 프로젝트: --project_id 플래그는 명령어가 작동하는 리소스 프로젝트를 지정합니다 (gcloud의 --project 플래그를 미러링함). --quota_project_id 플래그는 다운스트림 BigQuery API 호출의 청구/할당량에 대해 요금이 청구되는 프로젝트를 지정합니다 (gcloud의 --billing-project 플래그를 미러링함). 명령어에 --project_id가 지정되면 결제/할당량 프로젝트로 사용됩니다. --project_id를 지정하지 않거나 --quota_project_id를 추가로 지정하면 결제/할당량 프로젝트는 --quota_project_id 플래그에 설정된 프로젝트가 됩니다.
  3. 플래그 형식: 모든 긴 옵션에 대해 플래그 키와 값을 구분할 때는 항상 '=' 기호를 사용해야 합니다(MUST). 올바른 예: '--project_id=my-project' 또는 '--location=us' 잘못된 예: '--project_id my-project' 또는 '--location us' 플래그와 값 사이에는 공백을 사용하지 마세요.
  4. 구성 기본값 없음: bq 명령어가 상태 비저장 방식으로 실행됩니다. .bigqueryrc와 같은 로컬 구성 파일을 로드하지 않습니다. 따라서 모든 리전 작업(예: 데이터 세트 만들기 또는 리전 데이터 세트 쿼리)의 경우 --location 플래그(예: --location=us 또는 --location=EU)를 명시적으로 지정해야 합니다(MUST).
  5. 비동기 작업: 일부 명령어는 동기 장기 실행 작업 (예: 쿼리 작업 실행)을 시작합니다. 에이전트 시간 초과를 방지하려면 이러한 명령어에 항상 --nosync 플래그를 전달해야 합니다(SHOULD).
  6. 명령어 제한: bq init, bq pyshell, bq shell과 같은 bq 명령어를 사용하면 안 됩니다(MUST NOT). 명령어 파이핑 또는 체이닝은 지원되지 않습니다.
  7. 자가 수정: 명령어가 오류를 반환하면 stderr를 분석하고, 문법이나 플래그를 수정하고, 다음 반복에서 다시 시도합니다.

변경 bq 명령어의 예로는 bq mk, bq rm, bq update, bq insert, bq query(--dry_run 제외) 등이 있습니다. 사용법: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) 'command' 매개변수에 전체 bq 명령어를 단일 문자열로 제공해야 합니다(MUST). 결제, API 사용 설정, 할당량 사용량 확인을 위한 API 실행 프로젝트로 'project' 매개변수(형식: projects/PROJECT_ID)를 제공해야 합니다(MUST).

bq 명령어/패턴 예:

  1. 쿼리 실행: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROM project.dataset.table LIMIT 10'
  2. 데이터 세트 만들기: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. 테이블 만들기: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. 데이터 세트 삭제: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. 테이블 삭제: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. 테이블 설명 업데이트: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. 프로젝트의 데이터 세트를 나열합니다. bq ls --datasets=true --project_id=PROJECT_ID

MCP 도구 사양 가져오기

MCP 서버의 모든 도구에 대한 MCP 도구 사양을 가져오려면 tools/list 메서드를 사용하세요. 다음 예시에서는 curl을 사용하여 MCP 서버 내에서 현재 사용할 수 있는 모든 도구와 사양을 나열하는 방법을 보여줍니다.

curl 요청 
                      
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'