Claude Code를 사령탑으로, Antigravity CLI(Gemini 3.5 Flash)를 구현역으로 사용하는 환경 구축【종량제 과금

당초에는

Claude Fable

을 대상으로 기사를 쓰고 있었으나, 환경 구축 중에 Claude Fable를 사용할 수 없게 되는 대사건이 발생해 버렸습니다(웃음) ※Claude Opus 4.8

하지만 문제없이 사용할 수 있는 방법이므로 참고해 주시기 바랍니다.

"설계와 리뷰는 Claude, 코드 생성은 폭속의 Gemini 3.5 Flash에게 맡긴다" ── 이 역할 분담을 로컬에서 실현하는 환경을 구축했으므로, 절차와 주의할 점을 공유합니다.

포인트는 3가지입니다.

Claude Code를 사령탑으로 하고, Google의 **Antigravity CLI(agy로 호출)**를 MCP를 통해 서브 에이전트로 활용

• 구현역의 두뇌는 Gemini 3.5 Flash (High) (빠르고 저렴하며, 에이전트형 코딩에 적합)
• 종량제 과금 제로 ── API 키가 아니라 **AI Ultra/Pro 구독 범위(OAuth)**로 구동

이 기사는 실제로 구축하면서

빠졌던 함정과 해결책이 본체입니다. 동일한 구성을 시도하는 분들의 시간을 절약할 수 있다면 좋겠습니다 (2026년 6월 시점 / agy 1.0.8 / Windows 11).

담당	역할	이유
Claude Fable (Opus)	설계·사양 책정·생성 코드 검증·확정	규약 적합성이나 보안 등을 정확하게 검증할 수 있음
Gemini 3.5 Flash (High)	코드 생성의 주력 (구현·테스트)	생성이 매우 빠름. 방대한 구현을 한꺼번에 내놓을 수 있음

Antigravity(agy) 자체는 외부 MCP 서버를 호출하여 사용하는 "클라이언트" 측 제품입니다. 따라서 Claude Code에서 직접 MCP로 연결할 수는 없으며,

agy를 호출하는 브릿지(bridge)를 사이에 두는 구성이 됩니다.

Claude Code ──(MCP)──▶ 브릿지 server.py ──(subprocess)──▶ agy -p ──(OAuth)──▶ Gemini 3.5 Flash (High)
▲ AI Ultra/Pro 범위 (종량제 과금 없음)

"agy를 Claude Code에서 호출하기만 한다면, 명령어를 실행하는 단순한 MCP 서버로 충분하지 않을까?"라고 생각하실 것입니다. 하지만, 그렇게 하면 작동하지 않습니다. 이유는 agy 측의 버그 때문입니다.

agy -p "프롬프트" (비대화형 모드)에는, 모델과의 왕복은 완료되었음에도 불구하고 응답을 표준 출력(stdout)으로 전혀 반환하지 않는 버그가 있습니다 (공식 issue #76. exit code는 0이며, stderr도 비어 있는 까다로운 동작).

즉, 명령어의 표준 출력을 그대로 받아들이는 단순한 연계로는 응답을 전혀 가져올 수 없습니다. 하지만 실제 응답은 agy 자신이 작성하는 transcript 파일

~/.gemini/antigravity-cli/brain/<대화ID>/.system_generated/logs/transcript.jsonl

의 PLANNER_RESPONSE 엔트리에 들어 있습니다.

따라서, "agy -p를 실행하면서, 응답은 stdout이 아니라 transcript 파일로부터 읽어온다"라는 한 단계의 작업이 필요하게 됩니다.

이를 대신해 주는 것이 이번 브릿지로, 단순한 얇은 래퍼(wrapper)가 아니라 stdout 버그를 회피하기 위한 구현이 되어 있는 것입니다. 이번에는 OSS인 SinanTufekci/Claude-Code-Antigravity-CLI-MCP-Server를 이용했습니다.

즉 "MCP를 사용하는 이유"는 2단계입니다. ①Claude Code의 확장은 MCP가 표준이기 때문. ②agy -p가 응답을 반환하지 않으므로, transcript를 읽는 특수한 서버(브릿지)가 필요하기 때문입니다.

항목	확인 명령어	비고
Antigravity CLI	agy --version	1.0.8로 검증. AI Ultra/Pro에서 OAuth 로그인이 완료된 상태일 것
Python	python --version	3.10+
git	git --version	브릿지 취득에 사용

보충: 2026년, Google의 gemini

CLI는 Antigravity CLI로 전환되었습니다. 개인 AI Pro/Ultra 사용자는 agy를 사용합니다.

이미 도입했다면 건너뛰십시오. 미도입 상태라면 **공식(Google 소유 도메인)**에서 설치합니다.

Windows (PowerShell):

irm https://antigravity.google/cli/install.ps1 | iex

• 설치 경로는 C:\Users\<사용자명>\AppData\Local\agy\bin 입니다.
• PATH가 변경되므로, 터미널(및 Claude Code)을 재시작하십시오.
• 처음 실행 시 agy를 실행하여 인증 ── Google OAuth를 선택하고, AI Ultra/Pro 계정으로 로그인하십시오 (이것이 구독 범위 = 종량제 과금 제로의 기점입니다).
• 확인: agy --version

⚠️ 설치는 반드시 **공식 문서 (antigravity.google/docs/cli-install)**에서 최신 정보를 확인하십시오 (CLI 도입은 시스템에 변경을 가하므로, 출처가 공식 도메인인 것이 중요합니다. macOS / Linux 버전도 공식적으로 기재되어 있습니다).

agy의 인증은 --api-key 플래그 → 환경 변수 → OAuth 순으로 해결됩니다.

GEMINI_API_KEY 등이 설정되어 있으면, 구독 범위의 OAuth를 우회하여 종량제 API로 흐르게 됩니다. 먼저 모든 스코프에서 미설정 상태를 확인합니다 (모두 '미설정'이 되면 OK).

'GEMINI_API_KEY','ANTIGRAVITY_API_KEY' | %{ $n=$_; 'Process','User','Machine' | %{ "{0,-20}{1,-8}: {2}" -f $n,$_,$(if([Environment]::GetEnvironmentVariable($n,$_)){'★설정 있음'}else{'미설정'}) } }

%USERPROFILE%\.gemini\antigravity-cli\settings.json에 "model"을 추가합니다.

{
"model": "Gemini 3.5 Flash (High)"
}

나중에 설명하겠지만, --model 플래그가 아니라 이 settings.json 방식이 정답입니다.

"$env:USERPROFILE\tools\agy-mcp-bridge"는 환경에 맞춰 임의의 장소로 변경하십시오.

$dest = "$env:USERPROFILE\tools\agy-mcp-bridge"
git clone https://github.com/SinanTufekci/Claude-Code-Antigravity-CLI-MCP-Server.git $dest

clone 후, server.py의 내용은 반드시 육안으로 확인하십시오. 2026년 6월 13일 시점에서는 표준 라이브러리 + fastmcp만으로, ~/.gemini 하위 디렉토리를 읽기만 하는 얇은 구현이었습니다 (단, 후술할 보안 주의사항 있음).

python -m venv "$dest\.venv"
& "$dest\.venv\Scripts\python.exe" -m pip install fastmcp

claude mcp add agy -s user -- "$dest\.venv\Scripts\python.exe" "$dest\server.py"
claude mcp list # "agy: ... ✓ Connected"를 확인

재시작 후, mcp__agy__agy_ask / agy_continue / agy_status 등의 도구를 사용할 수 있게 됩니다. agy_status는 크레딧 소비 제로인 진단 도구입니다.

※ 최대의 함정인 "agy -p가 stdout에 응답을 반환하지 않는 문제"는 앞서 언급한(브릿지가 필요한 이유) 바와 같습니다. 브릿지를 사용하면 해결되지만, 직접 연동을 구축한다면 transcript를 읽는 구현이 필수적입니다.

agy -p를 stdin을 연 상태로 호출하면 **기동 직후 프리즈(freeze)**됩니다.

해결: subprocess

라면 stdin=subprocess.DEVNULL

, 쉘(shell)이라면 $null | agy -p "..."

와 같이 stdin을 닫습니다 (브릿지(bridge)는 이미 구현됨).

직관적으로는 agy -p --model "Gemini 3.5 Flash (High)" "..."

라고 하고 싶겠지만, 이 순서로 입력하면 무시되며 대화조차 생성되지 않습니다. ※--model을 -p 앞에 두면 적용됩니다.

해결: 절차 1과 같이 settings.json의 "model"에서 고정하는 것이 확실합니다. 이렇게 하면 순수한 agy -p 명령에서도 High 모델이 적용됩니다 (실기기에서 transcript의 Model Selection ... to Gemini 3.5 Flash (High)를 확인).

agy_status 실행 시 agy CLI [!!] not found on PATH가 발생했습니다. 조사 결과, User 환경 변수의 PATH에는 agy\bin이 있지만, MCP 서버에서는 보이지 않는 것이었습니다. Claude Code가 기동 시의 오래된 PATH를 상속받고 있으며, 기존 프로세스는 환경 변수의 변경 사항을 이어받지 않기 때문입니다 (Windows에서 흔히 발생하는 현상).

해결: PATH 반영에 의존하지 않고, agy의 전체 경로(full path)를 명시합니다.

• server.py의 agy 호출을 환경 변수 대응 방식으로 수정 (["agy", …] → [os.environ.get("AGY_BIN") or "agy", …], 2곳)
• env를 포함하여 재등록:

claude mcp add agy -s user -e AGY_BIN="%LOCALAPPDATA%\agy\bin\agy.exe" -- "<python>" "<server.py>"

사전 검증 팁:

$env:AGY_BIN="<전체 경로>"를 설정하고 스모크 테스트(smoke test)를 실행하여 PASS한다면, 재기동 후의 MCP에서도 확실하게 동작합니다.

AI Ultra/Pro 플랜은 추가 과금 없이 사용할 수 있지만, 일일 상한(daily limit)이 있습니다. 한도에 도달하면 일시 정지되므로, 무거운 생성 작업은 agy에 맡기고, 가벼운 편집은 사령탑(Claude)이 직접 수행하는 식의 배분이 유효합니다.

⚠️ 보안 주의: agy -p는 승인 게이트(approval gate) 없이 파일 쓰기, 명령 실행, 네트워크 전송을 수행하는 자율 에이전트(autonomous agent)입니다. --sandbox 옵션도 완전한 경계가 되지는 않습니다. 신뢰할 수 있는 프롬프트와 내용에만 사용하고, 중요한 변경 사항은 커밋 전에 git diff로 리뷰하십시오.

사령탑(Claude)에게 AI 협업 정책을 SKILL.md로 부여하여 다음과 같은 흐름으로 운영합니다.

① Claude가 설계 → ② agy가 High 모델로 초고속 생성 → ③ 정적 검사(테스트) → ④ Claude가 정밀 검토 → ⑤ 확정

필자는 직접 제작한 AI 코딩 특화 PHP 프레임워크인 Lattice (규약을 정적 검사 테스트로 기계적으로 강제하는 자기 검증형 프레임워크)로 테스트했습니다.

'자동 검사'를 ②와 ④ 사이에 끼워 넣는 것이 매우 강력하며, agy의 생성물이 규약을 위반하면 즉시 파악할 수 있습니다. 3층 구조(초고속 생성 · 자동 검사 · 인간급 리뷰)가 맞물리면 빠르고 정확한 개발 루프가 형성됩니다.

• Claude Code에서 Antigravity CLI를 MCP 브릿지로 호출하여, Claude=설계/검증 · Gemini Flash=생성의 분업을 실현함
• 브릿지가 필요한 이유: (공식 issue #76) ── 응답을 transcript에서 읽어야 하는 agy -p의 stdout 버그 때문
• 종량제 과금 제로 (OAuth 구독 플랜을 사용하며, GEMINI_API_KEY를 설정하지 않는 것이 핵심)
• 운영상의 함정은 stdin · 모델 지정 · PATH 상속 · 과금 경로의 4가지
• 프레임워크의 정적 검사 테스트를 협업 루프에 포함하면 품질이 기계적으로 담보됨

API 키를 사용하는 '프록시 방식'은 Google의 ToS(이용 약관) 위반으로 인한 BAN(계정 정지) 보고가 있어 채택하지 않았습니다. 구독 플랜을 정식으로 사용하는 본 구성이 비용 면에서도, 규약 면에서도 안심할 수 있는 방법입니다.