Google Cloud Next '26에서 Cloud Run의 풀 매니지드(Full-managed) 원격 MCP 서버가 발표되었습니다 (What's new for Cloud Run at Next '26). 요약하자면 "AI 에이전트에게 Cloud Run으로의 배포를 맡길 수 있는" MCP 서버입니다.

이 기사에서는 해당 공식 MCP 서버를 Claude Code에 연결하여, 샘플 애플리케이션을 "자연어"로 Cloud Run에 배포하는 과정까지 핸즈온(Hands-on)으로 확인합니다.

참고로 본문 중의 코드 블록은 라벨이 없는 것이 직접 실행하는 명령, 실행 결과가 해당 출력, Claude Code에 대한 지시 / 응답이 Claude Code와의 상호작용입니다.

대상 독자

• Claude Code / MCP를 막연하게 접해본 인프라·애플리케이션 엔지니어
• "에이전트에게 배포를 시키는 것"이 어디까지 실용적일지 궁금한 사람

Cloud Run에는 무기한 무료 티어(Free tier)가 있어, 월 200만 리퀘스트 / 180,000 vCPU초 / 360,000 GB초까지 무료입니다. 이번과 같은 hello world를 1회 배포하여 동작 확인하는 정도라면, 컴퓨팅 비용은 거의 무료 범위 내에 들어옵니다.

유일한 실제 비용은 빌드한 컨테이너 이미지를 Artifact Registry에 저장하는 비용(수 MB~이며 월 몇 엔 수준)입니다. 마지막에 정리하면 사라집니다.

필요한 것

• Google Cloud 프로젝트 (결제 활성화 필요. 무료 범위 내라도 결제 계정 연결은 필요함)
• gcloud CLI (인증됨)
• Node.js 18 이상 (MCP 서버를 npx로 실행하기 때문)
• Claude Code

권한이 제한된 계정으로 테스트할 경우, 직접 움직이기 전에 자신의 실효 권한을 확인해 두면 막히지 않습니다. 프로젝트에 대한 권한 체크는 gcloud 서브 명령어가 없으므로, Resource Manager의 testIamPermissions API를 직접 호출합니다.

export PROJECT_ID="YOUR_PROJECT_ID"
curl -sS -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)"
...

이 API는 "자신이 가진 권한만" 반환하는 사양이기 때문에, 반환되지 않은 것이 부족한 권한입니다. 그룹을 통해 상속받은 권한을 포함한 실효 권한을 볼 수 있습니다.

특히 iam.serviceAccounts.actAs는 놓치기 쉽습니다. Cloud Run은 서비스 실행 ID로서 서비스 계정(기본적으로 Compute Engine의 기본 SA)을 사용하기 때문에, 배포하는 측에 해당 SA를 "사용"할 권한이 필요합니다. 이것이 없으면 빌드 단계에도 도달하지 못하고 드라이 런(Dry run) 단계에서 거부됩니다.

7 PERMISSION_DENIED: Permission 'iam.serviceAccounts.actAs' denied on
service account PROJECT_NUMBER-compute@developer.gserviceaccount.com
(or it may not exist)

필요한 역할(Role)은 roles/iam.serviceAccountUser입니다. 직접 부여할 수 없는 경우에는 프로젝트 관리자에게 요청해야 하므로, 착수 전에 확인해 두면 재작업을 방지할 수 있습니다.

💡 TLS 인터셉트를 수행하는 프록시 하에서는

--cacert /path/to/ca-bundle.pem

지정이 필요할 수 있습니다.

API도 3개가 활성화되어 있는지 확인해 둡니다.

gcloud services list --enabled --project "$PROJECT_ID" \
--format="value(config.name)"
| grep -E 'run\.googleapis\.com|cloudbuild\.googleapis\.com|artifactregistry\.googleapis\.com'

3개가 갖춰지면 모두 유효합니다. 부족하다면 gcloud services enable을 통해 활성화합니다 (serviceusage.services.enable 권한이 필요합니다).

⚠️

이 기사의 검증 환경에 대하여

필자는 처음에 이전에 사용하던 기존 프로젝트에서 시도하다가 막혔습니다 (후술할 "실수" 부분). 최종적으로는 새로 만든 프로젝트에서 완주했습니다. 간편하게 테스트하려면 새 프로젝트를 준비하는 것이 확실합니다.

이 부분이 가장 혼동되기 쉬우므로 먼저 구분하겠습니다. "Cloud Run과 MCP"에 관한 이야기에는 두 가지 별개의 대상이 있습니다.

| 역할 |
|---|---|
| ① Cloud Run에 배포하기 위한 MCP 서버 |
에이전트에게 "이것 좀 배포해줘"라고 말하면 Cloud Run에 앱이 올라갑니다. 이번에 발표된 것이 이것입니다 | ✅ |
| ② Cloud Run 위에 직접 만든 MCP 서버를 호스트하기 |
직접 작성한 MCP 서버를 Cloud Run에 컨테이너로서 올려서 공개합니다 | ❌ (이번에는 다루지 않음) |

이 기사에서 다루는 것은 ①입니다. ②는 "MCP 서버의 위치로서 Cloud Run을 사용한다"는 별개의 테마이며, 섞이면 한꺼번에 이해하기 어려워지므로 나누어 생각합니다.

①의 실체는 GitHub에 공개되어 있는 GoogleCloudPlatform/cloud-run-mcp입니다. 제공되는 도구는 다음과 같습니다.

| 도구 |
|---|---|
| deploy_local_folder |
로컬 폴더 전체를 배포 |
| deploy_file_contents |
파일 내용을 직접 전달하여 배포 |
| deploy_container_image |
기존 컨테이너 이미지(Container Image)를 배포 |
| list_services |
서비스 목록 |
| get_service |
서비스 상세 정보 (URL 등) |
| get_service_log |
로그 및 에러 취득 |
| list_projects |
GCP 프로젝트 목록 |
| create_project |
GCP 프로젝트 신규 생성 |

총 8개입니다. create_project까지 갖추고 있는 점을 통해, 이 MCP 서버가 어디까지 수행할 수 있도록 설계되었는지 알 수 있습니다.

여기에 더해 deploy / logs라는 프롬프트 (Prompt) (자연어 단축키)도 동봉되어 있습니다.

MCP 서버는 로컬의 Google Cloud 인증 정보 (ADC, Application Default Credentials)를 사용하여 배포합니다. 먼저 두 가지 인증을 통과시킵니다.

# 사용자 인증
gcloud auth login
# 애플리케이션 기본 인증 (ADC)
...

Claude Code에는 MCP를 CLI에서 등록하는 명령어가 있습니다. 터미널에서 (Claude Code 세션 내부가 아니라) 실행합니다.

claude mcp add cloud-run -- npx -y @google-cloud/cloud-run-mcp

Added stdio MCP server cloud-run with command: npx -y @google-cloud/cloud-run-mcp to local config
File modified: /Users/YOUR_NAME/.claude.json [project: /Users/YOUR_NAME/path/to/workdir]

-- 뒤가 서버를 실행하는 명령어입니다.

위 출력의 [project: ...] 부분에 주목해 주세요. 기본값은 **local 스코프 (local scope)**이며, 실행한 디렉토리에 종속되어 등록됩니다.

이후 샘플 앱을 가져오기 위해 git clone을 하고 다른 디렉토리로 이동하면, 그곳은 별개의 프로젝트로 취급되어 등록한 cloud-run이 보이지 않습니다 (local 스코프는 git 리포지토리의 루트, git이 아니라면 해당 디렉토리에 종속되기 때문입니다).

어느 디렉토리에서든 사용하고 싶으므로, user 스코프로 다시 등록하겠습니다.

claude mcp remove cloud-run --scope local
claude mcp add --scope user cloud-run -- npx -y @google-cloud/cloud-run-mcp

Removed MCP server cloud-run from local config
File modified: /Users/YOUR_NAME/.claude.json [project: /Users/YOUR_NAME/path/to/workdir]
Added stdio MCP server cloud-run with command: npx -y @google-cloud/cloud-run-mcp to user config
...

두 번째 File modified:에 [project: ...]가 붙어있지 않은 것이 user 스코프의 표시입니다. 팀과 공유하고 싶다면 --scope project를 사용하면 .mcp.json에 기록되어 리포지토리에 커밋하여 배포할 수 있습니다.

참고로, user 스코프로 등록이 되어 있다면 나중에 샘플용 디렉토리로 이동한 후에도 세션 내의 /mcp에서 User MCPs로 표시됩니다.

Manage MCP servers
User MCPs (/Users/YOUR_NAME/.claude.json)
cloud-run · ✔ connected · 8 tools

필요하다면, 기본 프로젝트나 리전을 환경 변수로 전달할 수 있습니다.

claude mcp add --scope user cloud-run \
-e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID \
-e GOOGLE_CLOUD_REGION=asia-northeast1 \
...

claude mcp list

cloud-run: npx -y @google-cloud/cloud-run-mcp - ✔ Connected

✔ Connected가 되어 있으면 OK입니다.

필자의 경우, 첫 번째 실행에서는 ✘ Failed to connect였습니다.

npx가 최초에 패키지를 가져오기 때문에, 등록 직후에는 구동이 맞지 않을 수 있습니다. 잠시 기다린 후 재실행했더니 ✔ Connected로 바뀌었습니다. 당황해서 설정을 의심하기 전에, 먼저 1회 리트라이 해보세요. 그래도 연결되지 않는 경우에는, MCP 서버를 직접 구동하면 순수한 에러가 보입니다.

npx -y @google-cloud/cloud-run-mcp

구동해서 입력 대기 상태로 멈춘다면 서버 자체는 정상이고, Claude Code 측의 구동 타임아웃(기본값 30초)을 의심해야 합니다.

MCP_TIMEOUT=60000 claude

주제로는 공식 리포지토리에 포함된 Node.js 샘플을 사용합니다. 내용은 Express의 hello world입니다.

const express = require('express');
const app = express();
const port = process.env.PORT || 8080;
...

리포지토리를 clone하여, 이 폴더에서 Claude Code를 구동합니다.

git clone https://github.com/GoogleCloudPlatform/cloud-run-mcp.git
cd cloud-run-mcp/example-sources-to-deploy/nodejs
claude

나머지는 세션 내에서, 한국어로 이렇게 요청하기만 하면 됩니다.

이 폴더를 Cloud Run에 배포해 줘. 서비스 이름은 hello-mcp로 해 줘.

Claude Code가 deploy_local_folder 도구를 호출하고, 처음에는 도구 사용 허가를 요청합니다.

도구 사용 (Tool use)
cloud-run - deploy_local_folder(project: "YOUR_PROJECT_ID", folderPath: 
"/Users/YOUR_NAME/path/to/cloud-run-mcp/example-sources-to-deploy/nodejs",
...

인수(배포 대상 프로젝트, 폴더, 리전, 서비스 이름)가 모두 명시되어 있으므로, 실행 전에 의도한 대로인지 확인할 수 있습니다.

여기에서 ** 2. Yes, and don't ask again**이라는 선택지가 나오는데, 적어도 배포 관련 도구에서는 선택하지 않는 것을 권장합니다. 이후 해당 디렉토리에서는 확인 절차 없이 배포가 실행되기 때문입니다. "편리하니까 전부 허용"하는 방식은, 되돌리기 어려운 작업일수록 신중해야 합니다.

배포가 시작되면 Cloud Build를 통한 빌드 → Cloud Run으로의 배포가 진행되며, 마지막에 서비스 URL이 반환됩니다. 필자의 환경에서는 약 2분 반 정도 걸려 완료되었습니다.

배포가 완료되었습니다.
서비스 이름 : hello-mcp
리전 : asia-northeast1
...

샘플에는 Dockerfile이 없기 때문에, Cloud Run의 소스 배포 (Buildpacks)를 통해 컨테이너화되었습니다. index.js와 package.json을 두기만 하면 되며, 컨테이너를 직접 준비할 필요는 없습니다.

/ (슬래시) 메뉴에서 동봉된 프롬프트의 deploy를 선택하는 방식으로도 동일하게 수행할 수 있습니다.

지금까지 콘솔도 배포용 명령어도 전혀 사용하지 않았습니다.

반환된 URL을 그대로 엽니다.

curl -s -o /dev/null -w "%{http_code}\n" https://hello-mcp-xxxxxxxxxx-an.a.run.app

200

인증 헤더를 붙이지 않았음에도 200이 반환됩니다. 브라우저로 열어도 마찬가지로 바로 표시됩니다.

📷

이미지: 브라우저에서 Service URL을 연 상태

프레임: "Hello from Node.js on Cloud Run!" 표시

마스크: 주소창의 URL (호스트 부분) / 북마크 바

📷

이미지 (임의): Cloud Run 콘솔의 서비스 상세

hello-mcp가 녹색 체크와 함께 가동 중인 화면

마스크: URL의 프로젝트 번호 / 우측 상단의 계정 이메일 주소

콘솔을 한 번도 열지 않고, 채팅으로 요청한 것만으로 공개된 서비스가 하나 구축되었습니다. 이 "공개되어 있다"는 점이 후반부의 핵심 주제가 됩니다.

배포한 서비스의 상태도 그대로 Claude Code에게 물어볼 수 있습니다.

아까 그 hello-mcp 서비스의 로그를 보여줘.

get_service_log 도구가 호출되어, 최근 로그와 에러가 반환됩니다. 이 또한 / 메뉴의 logs 프롬프트를 통해 실행할 수 있습니다.

[06:07:01] INFO GET / → 200 (223 Byte)
[06:04:56] INFO GET / → 200 (223 Byte)
[06:03:57] INFO Services.CreateService: Ready condition → True (Service hello-mcp)
...

배포 → 동작 확인 → 로그 확인까지, 도구를 전환하지 않고 하나의 대화로 완결되는 것이 경험 측면에서의 강점입니다.

그리고 이 로그를 보고 나서야 처음으로 깨달은 것이 있습니다. 서두에 ERROR가 2건 있습니다.

Runtime nodejs26 is not supported

— Buildpacks가 Node.js 26을 선택하여 2번 실패했고, 그 후 지원 대상 런타임(Runtime)으로 폴백(Fallback)하여 성공했습니다. 최종적으로 서비스는 정상적으로 작동하고 있지만, 이 과정에서 약 1분 20초 정도를 소비했습니다.

하지만 에이전트의 완료 보고는 "배포가 완료되었습니다"라는 URL뿐이었습니다. 중간에 2번 실패했다는 사실은 보고에 나타나지 않습니다. MCP 도구의 반환값(Return value) 측면에서는 성공이기 때문에, 거기까지는 보이지 않는 것입니다.

「부탁만 하면 배포할 수 있다」는 경험의 이면에서 실제로 어떤 일이 일어나고 있는지는 결국 로그를 확인하지 않으면 알 수 없습니다. 편리한 인터페이스일수록 별도의 확인 수단을 갖춰둘 필요가 있다는 뜻이라고 생각합니다. 그런 의미에서 get_service_log가 동일한 MCP 서버에 포함되어 있는 것은 일리가 있습니다.

여기서 한 번 막혔기 때문에, 문제 분리(Troubleshooting) 과정을 기록해 둡니다. 동일한 환경을 사용하는 분들은 높은 확률로 이 문제를 겪게 될 것입니다.

증상: 배포를 요청하면, 에이전트가 "프로젝트 목록이 빈 값으로 반환되었습니다"라고 말하기 시작한다. 인증 문제를 의심하여 gcloud auth list나 ADC (Application Default Credentials)를 확인해도 모두 정상이다. gcloud projects list를 실행하면 프로젝트가 제대로 보인다.

구현을 보면 이유를 알 수 있습니다. lib/cloud-api/projects.js의 listProjects는 다음과 같이 되어 있습니다.

try {
const [projects] = await client.searchProjects();
return projects.map((project) => ({ id: project.projectId }));
...

"목록이 비어 있음"은 프로젝트가 없다는 의미가 아니라, API 호출이 실패한 결과였습니다. 에러가 console.error로 흘러갈 뿐이라서, MCP 클라이언트 측에는 그저 "비어 있음"으로만 보이고 인증 문제로 오해를 불러일으킵니다.

그래서 에러가 무시되기 전에 직접 확인해 봅니다.

node -e "
import('@google-cloud/resource-manager').then(async (m) => {
try { const r = await new m.ProjectsClient().searchProjects(); console.log('OK', r[0].length); }
...

ERR 14 UNAVAILABLE: No connection established. Last error: Protocol error

gRPC가 통하지 않았습니다. 반면, 동일한 API를 REST로 호출하면 정상적으로 작동합니다.

curl -sS -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://cloudresourcemanager.googleapis.com/v1/projects" | head -5

이러한 비대칭성이 까다로워서, "인증은 통과하는데 목록만 비어 있는" 혼란스러운 상태를 만듭니다.

원인은 VPN 클라이언트가 HTTP/2 = gRPC를 통과시키지 못하고 있었던 것이었습니다. VPN을 해제하자 동일한 명령어가 OK를 반환하기 시작했습니다.

cloud-run-mcp는 Cloud Run이나 Service Usage 조작에 gRPC 기반의 클라이언트 라이브러리를 사용하고 있습니다 (lib/clients.js의 주석에도 명시되어 있습니다). 즉, list_projects에 국한되지 않고 배포 본체도 동일한 경로를 사용합니다. gRPC가 차단된 환경에서는 이 MCP 서버는 거의 기능하지 않습니다.

요약하자면:

VPN이 필수인 환경에서 사용하고 싶다면, 이 MCP 서버 대신 gcloud run deploy로 솔직하게 폴백(Fallback)하는 것이 현실적입니다.

사소한 이야기지만, cloud-run-mcp 리포지토리에는 MCP 서버 구현뿐만 아니라 skills/cloud-run/SKILL.md라는 Skill도 동봉되어 있습니다. 내용은 gcloud run 사용법 (services의 list / describe / update / logs read 등)을 정리한 것입니다.

MCP(=도구로서 기능을 전달)와 Skill(=절차에 대한 지식을 전달)이 동일한 리포지토리에서 두 계층으로 제공되는 구조를 띠고 있습니다. "에이전트에게 무언가를 시킬 때"의 표준화가 도구 측과 지식 측이라는 두 바퀴로 진행되고 있다는 점을 엿볼 수 있어, 개인적으로 흥미로운 포인트였습니다.

여기까지 해서 '편리함'은 충분히 전달되었을 것이라 생각합니다. 마지막으로, 업무에서 사용하기 전에 반드시 알아두어야 할 동작이 하나 있습니다.

cloud-run-mcp에는 SKIP_IAM_CHECK라는 환경 변수가 있습니다. 구현은 다음과 같습니다.

const skipIamCheck = process.env.SKIP_IAM_CHECK !== 'false';

!== 'false'이므로, 아무것도 설정하지 않으면 true입니다. 그리고 이 플래그가 설정되어 있으면, 배포 시 서비스에 다음과 같은 설정이 들어갑니다.

if (skipIamCheck) {
service.invokerIamDisabled = true;
}

즉, 기본값으로 배포하면 해당 서비스는 누구나 접근할 수 있는 상태가 됩니다. 실제로 배포 직후 인증 헤더 없이 호출하면 통과됩니다.

curl -s -o /dev/null -w "%{http_code}\n" https://hello-mcp-xxxxxxxxxx-an.a.run.app

200

여기까지는 "뭐, 그런 옵션이 있구나" 하고 넘어갈 수 있는 이야기입니다. 문제는 지금부터입니다.

공개 상태를 확인하려고 IAM 정책 (IAM Policy)을 살펴보면 다음과 같습니다.

gcloud run services get-iam-policy hello-mcp --region asia-northeast1

etag: ACAB

비어 있습니다. allUsers에 대한 바인딩 (Binding)은 존재하지 않습니다. 프로젝트 레벨에서 확인해도 마찬가지입니다.

gcloud projects get-iam-policy "$PROJECT_ID" \
--flatten="bindings[].members" \
--filter="bindings.members:allUsers OR bindings.members:allAuthenticatedUsers" \
...

（아무것도 반환되지 않음）

비결은 invokerIamDisabled입니다. 이것은 "이 서비스에서는 invoker의 IAM 체크를 아예 수행하지 않는다"라는 서비스 측의 설정으로, IAM 정책을 전혀 변경하지 않고 인증을 무효화합니다. Cloud Run Admin API v2를 직접 확인하면 이를 알 수 있습니다.

curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://run.googleapis.com/v2/projects/${PROJECT_ID}/locations/asia-northeast1/services/hello-mcp" \
| python3 -m json.tool | grep -iE "invoker|ingress"

"ingress": "INGRESS_TRAFFIC_ALL",
"invokerIamDisabled": true,

정리하면 다음과 같습니다.

콘솔에서 보면 알 수 있습니다. 서비스 상세 정보의 "보안" 탭에는 "퍼블릭 액세스 허용"이 선택되어 있으며, 설명에도 인증 체크가 실행되지 않는다는 내용이 적혀 있습니다.

📷

이미지: 서비스 상세 → 보안 탭

"퍼블릭 액세스 허용"이 선택된 상태

마스크: 불필요

문제는 IAM 정책을 보는 방식으로는 알 수 없다는 점입니다.

이는 운영 측면에서 상당히 심각한 문제입니다. "allUsers 바인딩을 검색하여 공개 리소스를 전수 조사하는" 방식의 자산 실사는 많은 현장에서 이루어지고 있을 것입니다. 하지만 이 방법으로는 invokerIamDisabled로 공개된 서비스는 단 한 건도 걸러내지 못합니다. gcloud run services get-iam-policy 역시 빈 값을 반환합니다.

콘솔을 하나씩 열어본다면 알아챌 수 있겠지만, 서비스가 수십 개 있는 프로젝트에서 전부 육안으로 확인하는 운영 방식은 현실적이지 않습니다. 스크립트로 재고 조사를 해도 놓치게 되는 성격의 허점입니다.

게다가 기본값이 true입니다.

따라서, 아무것도 지정하지 않으면 이 상태가 됩니다. 에이전트에게 "배포해 줘"라고 부탁하는 것만으로, IAM 정책에는 나타나지 않는 공개 서비스가 늘어가는 구도입니다.

대책으로는, 우선 MCP 서버를 등록할 때 명시적으로 비활성화해 두는 것이 확실합니다.

claude mcp add --scope user cloud-run \
-e SKIP_IAM_CHECK=false \
-- npx -y @google-cloud/cloud-run-mcp

그 상태에서 공개 리소스를 재고 조사하려면, IAM 정책뿐만 아니라 서비스 설정의 invokerIamDisabled도 함께 확인해야 합니다.

# 대략적으로 모든 서비스를 체크하는 예시
for s in $(gcloud run services list --region asia-northeast1 --format="value(metadata.name)"); do
flag=$(curl -sS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
...

편리함을 부정하고 싶은 것은 아닙니다. 다만, 개인적으로 테스트할 때의 기본값과 업무에서 사용할 때의 기본값은 달라도 된다고 생각합니다. 에이전트에게 배포를 맡긴다면, 이 하나의 환경 변수는 처음에 결정해 두어야 합니다.

검증이 끝나면 삭제하겠습니다.

# Cloud Run 서비스 삭제
gcloud run services delete hello-mcp --region asia-northeast1
# (필요 없다면) MCP 서버 등록도 해제
...