Antigravity MCP

A workspace containing a Python-based Model Context Protocol (MCP) server integrated with the Google Antigravity SDK and Google Cloud Gemini Enterprise Agent Platform (Gemini), accompanied by a responsive test client web application.

• English Documentation

• 한국어 문서

English Documentation

Project Structure

This workspace is divided into two main parts:

1. mcp-server/: The Core Python MCP Server.

   • Leverages FastMCP and the google.antigravity SDK.

   • Exposes tools like agy_task and agy_code_review.

2. test-mcp-client/: A local test web application.

   • Built on Starlette and Uvicorn.

   • Provides a web interface to easily test the MCP Server.

   • Connects to the MCP server via SSE on port 8000 automatically, or falls back to STDIO if the persistent server is offline.

Related MCP server: gpal

System Architecture & Multi-Agent Routing

The interaction model features a collaborative Multi-Agent Routing architecture between the parent orchestrator (Claude Code) and the specialized downstream agent (Antigravity Agent).

graph TD
    CC["Claude Code CLI"] -->|"SSE / STDIO"| MS["AGY MCP Server"]
    TWC["Test Web Client"] -->|"SSE / STDIO"| MS
    
    MS -->|"Invoke SDK / Initialize Agent"| Agent["Antigravity Agent"]
    Agent -->|"Gemini API Call"| Vertex["Gemini Enterprise Agent Platform"]
    
    Agent -.->|"Write telemetry"| Log["Telemetry Log<br>(thinking.log)"]
    TWC -.->|"Tail logs"| Log

    style CC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style TWC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style MS fill:#bbf,stroke:#333,stroke-width:2px
    style Agent fill:#f9f,stroke:#333,stroke-width:2px
    style Vertex fill:#bfb,stroke:#333,stroke-width:2px
    style Log fill:#ffe,stroke:#333,stroke-width:1px

Technical Workflow & Multi-Agent Routing Mechanics

1. Claude Code as the Parent Orchestrator (Top-Level Router) When the user enters a prompt containing terms like antigravity, agy, gemini, or 제미나이, Claude Code acts as the orchestrator. Rather than executing general tasks blindly, it matches semantic trigger words dynamically to discover our specialized MCP tools.

2. Cohesive Semantic Synonym Routing Because the FastMCP tools (agy_task, agy_code_review) are decorated with rich semantic docstrings, Claude Code delegates the domain-specific tasks to the AGY MCP Server. This avoids spinning up multiple redundant servers, preventing resource overhead and API conflicts.

3. Delegation to Antigravity Agent (Specialized Downstream Execution) The AGY MCP Server accepts the JSON-RPC request and spawns a highly specialized, autonomous Antigravity Agent. Powered by Gemini, the agent performs localized work (such as code modifications or deep repository reviews) and streams token-by-token reasoning telemetry.

4. Telemetry Log Inference logs generated during agent execution are stored outside the workspace directory at ~/.gemini/antigravity/thinking.log.

Installation & Server Setup Guide

Follow these steps to set up the MCP server for the first time on any system (Windows, macOS, or Linux).

1. Prerequisites

• Python 3.10+ installed on your system.

• Google Cloud SDK (gcloud CLI) installed and configured.

• A GCP Project with the Gemini Enterprise Agent Platform APIs enabled.

2. Google Cloud Authentication

Authenticate your local environment to allow the Antigravity SDK to access Gemini:

gcloud auth application-default login

3. Initialize Python Virtual Environment

Set up a clean virtual environment and install dependencies:

# Create venv
python -m venv agy-mcp-env

# Activate venv
# On macOS/Linux:
source agy-mcp-env/bin/activate
# On Windows (PowerShell):
.\agy-mcp-env\Scripts\Activate.ps1
# On Windows (CMD):
.\agy-mcp-env\Scripts\activate.bat

# Install required packages
pip install -r requirements.txt

4. Configuration Settings

Create a configuration file named mcp-server/agy-mcp-config.json inside your project root to point the server to your GCP resources:

{
  "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
  "GCP_LOCATION": "<YOUR_GCP_LOCATION>",
  "MODEL": "gemini-3.5-flash"
}

Integrating with Claude Code

You can integrate this server into Claude Code using either of the two transport options below depending on your runtime architecture.

Option 1: STDIO Transport Mode (Recommended)

In this mode, Claude Code directly spawns the Python MCP server as a background subprocess during execution.

A. Windows Setup (PowerShell)

Locate your Claude Code global configuration file (typically %USERPROFILE%\.claude.json or C:\Users\<username>\.claude.json). Update or create the file with the following configuration:

{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>\\agy-mcp-env\\Scripts\\python.exe",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>\\mcp-server\\server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}

B. macOS / Linux Setup

Locate your Claude Code global configuration file (typically ~/.claude.json). Update or create the file with the following configuration:

{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>/agy-mcp-env/bin/python",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>/mcp-server/server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}

Option 2: Server (SSE) Transport Mode

In this mode, the MCP server runs persistently in a separate terminal process as an HTTP server, and Claude Code communicates with it over Server-Sent Events (SSE).

1. Launch the Standalone Server

Run the following command in a separate terminal window to start the persistent server on port 8000:

• On macOS / Linux:

  agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000

• On Windows:

  .\agy-mcp-env\Scripts\python.exe mcp-server\server.py --transport sse --port 8000

2. Configure Claude Code Config File

Locate your global Claude Code configuration file (~/.claude.json or %USERPROFILE%\.claude.json). Register the persistent server endpoint by updating the file with the following:

{
  "mcpServers": {
    "agy": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Running the Components

A. Run the Test Client (Web UI)

To launch the test web app:

# Using macOS/Linux activated venv or direct path:
agy-mcp-env/bin/python test-mcp-client/app.py

# Using Windows direct path:
.\agy-mcp-env\Scripts\python.exe test-mcp-client\app.py

Open http://127.0.0.1:5001 in your browser. It will automatically detect your live SSE server on port 8000 or fall back to spawning its own STDIO background subprocess!

B. Run the MCP Server Directly

If you want to run the server in standalone SSE mode on port 8000:

agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000

References

• Google Antigravity Python SDK Repository

한국어 문서

프로젝트 구조

본 프로젝트는 Google Antigravity SDK 및 Google Cloud Gemini Enterprise Agent Platform (Gemini) 기반의 파이썬 Model Context Protocol (MCP) 서버와 이를 테스트할 수 있는 반응형 웹 애플리케이션으로 구성되어 있습니다.

1. mcp-server/: 핵심 파이썬 MCP 서버.

   • FastMCP 및 google.antigravity SDK 활용.

   • agy_task 및 agy_code_review 도구 제공.

2. test-mcp-client/: 로컬 테스트용 웹 애플리케이션.

   • Starlette 및 Uvicorn 기반 설계.

   • MCP Server를 테스트해볼 수 있는 웹 인터페이스입니다.

   • 활성화된 포트 8000 SSE 서버를 우선 감지하며, 오프라인 시 백그라운드 서브프로세스(STDIO 방식)로 MCP 서버를 유연하게 자동 연동.

시스템 아키텍처 및 멀티 에이전트 라우팅 (Multi-Agent Routing)

본 작업 공간은 상위 조율자(Claude Code)와 하위 실행자(Antigravity Agent) 간의 유기적인 멀티 에이전트 라우팅(Multi-Agent Routing) 구조를 채택하고 있습니다. 전체 상호작용 및 통신 구조는 다음과 같습니다:

graph TD
    CC["Claude Code CLI"] -->|"SSE / STDIO"| MS["AGY MCP 서버"]
    TWC["테스트 웹 앱"] -->|"SSE / STDIO"| MS
    
    MS -->|"SDK 호출 및 초기화"| Agent["Antigravity 에이전트"]
    Agent -->|"Gemini API 호출"| Vertex["Gemini Enterprise Agent Platform"]
    
    Agent -.->|"기록 저장"| Log["Telemetry Log<br>(thinking.log)"]
    TWC -.->|"로그 파싱"| Log

    style CC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style TWC fill:#d4f0ff,stroke:#333,stroke-width:2px
    style MS fill:#bbf,stroke:#333,stroke-width:2px
    style Agent fill:#f9f,stroke:#333,stroke-width:2px
    style Vertex fill:#bfb,stroke:#333,stroke-width:2px
    style Log fill:#ffe,stroke:#333,stroke-width:1px

기술 워크플로우 및 멀티 에이전트 라우팅 동작 원리

1. 상위 오케스트레이터로서의 Claude Code (최상위 라우터) 사용자가 antigravity, agy, gemini, 제미나이 등의 키워드로 작업을 내리면 Claude Code가 최상위 중재자가 됩니다. 작업을 맹목적으로 자체 수행하는 대신, 의미론적 키워드 매칭을 통해 가장 적합한 전용 MCP 도구를 검색합니다.

2. 통합 의미론적 동의어 라우팅 (Cohesive Semantic Synonym Routing) FastMCP 도구들(agy_task, agy_code_review)의 docstring에 상세한 의미론적 키워드가 설계되어 있어, Claude Code가 이를 동적으로 감지하여 당사 MCP 서버로 위임(Routing)합니다. 이를 통해 다수의 서버를 개별 실행하지 않고 단일 진입점에서 안정적인 자원 제어가 가능해집니다.

3. 하위 전문 에이전트로의 자율 위임 (Antigravity Agent 실행) AGY MCP 서버는 위임 요청(JSON-RPC)을 수신한 즉시 내부적으로 하위 전문 에이전트(Antigravity Agent)를 동적으로 생성합니다. 이 에이전트는 Google Cloud Gemini Enterprise Agent Platform의 고성능 추론 능력을 직접 활용하여 로컬 파일 편집 및 고도화된 코드 리뷰를 전담 수행합니다.

4. 텔레메트리 로그 에이전트 실행 시 발생하는 추론 과정은 프로젝트 디렉터리 바깥 경로(~/.gemini/antigravity/thinking.log)에 저장합니다.

설치 및 서버 설정 가이드

처음 프로젝트를 시작하는 개발자도 쉽게 따라 할 수 있도록 정리된 단계별 가이드입니다 (Windows, macOS, Linux 지원).

1. 사전 준비 사항

• Python 3.10 이상이 시스템에 설치되어 있어야 합니다.

• Google Cloud SDK (gcloud CLI) 가 설치 및 로그인 설정되어 있어야 합니다.

• Gemini Enterprise Agent Platform API 가 활성화된 Google Cloud 프로젝트가 필요합니다.

2. Google Cloud 인증 등록

로컬 터미널 환경에 Google Cloud 권한을 이식해 Gemini Enterprise Agent Platform 및 Gemini 모델에 연결할 수 있도록 설정합니다:

gcloud auth application-default login

3. 파이썬 가상환경 초기화 및 의존성 설치

새로운 가상환경을 구성하고 프로젝트에 필요한 라이브러리 패키지들을 설치합니다:

# 가상환경 생성
python -m venv agy-mcp-env

# 가상환경 활성화
# macOS/Linux 환경:
source agy-mcp-env/bin/activate
# On Windows (PowerShell):
.\agy-mcp-env\Scripts\Activate.ps1
# On Windows (CMD):
.\agy-mcp-env\Scripts\activate.bat

# 필수 패키지 설치
pip install -r requirements.txt

4. GCP 환경 변수 및 설정 파일 작성

mcp-server/ 디렉터리 하위에 설정 파일 agy-mcp-config.json을 새로 작성하여 서버가 접근할 GCP 자원을 선언합니다:

{
  "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
  "GCP_LOCATION": "<YOUR_GCP_LOCATION>",
  "MODEL": "gemini-3.5-flash"
}

Claude Code 연동 방법

이 서버를 Claude Code에 연동하는 방법은 런타임 구성 방식에 따라 아래 두 가지 옵션 중 하나를 선택하여 진행할 수 있습니다.

옵션 1: STDIO 통신 모드 (추천)

이 모드에서는 Claude Code가 백그라운드 서브프로세스로 파이썬 MCP 서버를 직접 구동하고 필요한 시점에 통신합니다.

A. Windows 환경 설정 (PowerShell)

Claude Code의 글로벌 설정 파일(일반적으로 %USERPROFILE%\.claude.json 또는 C:\Users\<사용자명>\.claude.json)을 찾아 아래와 같이 수정하거나 생성합니다:

{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>\\agy-mcp-env\\Scripts\\python.exe",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>\\mcp-server\\server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}

B. macOS / Linux 환경 설정

Claude Code의 글로벌 설정 파일(일반적으로 ~/.claude.json)을 찾아 아래와 같이 수정하거나 생성합니다:

{
  "mcpServers": {
    "agy": {
      "command": "<WORKSPACE_ABSOLUTE_PATH>/agy-mcp-env/bin/python",
      "args": [
        "<WORKSPACE_ABSOLUTE_PATH>/mcp-server/server.py"
      ],
      "env": {
        "GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
        "GCP_LOCATION": "<YOUR_GCP_LOCATION>"
      }
    }
  }
}

옵션 2: 서버 모드 (SSE 통신 모드)

이 모드에서는 MCP 서버를 별도의 독립된 터미널 런타임에서 백그라운드 HTTP 서버로 상시 대기 구동하며, Claude Code가 Server-Sent Events(SSE) 프로토콜을 통해 연결을 요청합니다.

1. 독립형 서버 실행

별도의 터미널 창을 열고 아래 명령어를 기동하여 포트 8000번으로 영속(Persistent) 서버를 시작합니다:

• macOS / Linux 환경:

  agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000

• Windows 환경:

  .\agy-mcp-env\Scripts\python.exe mcp-server\server.py --transport sse --port 8000

2. Claude Code 설정 파일 등록

Claude Code 글로벌 설정 파일(~/.claude.json 또는 %USERPROFILE%\.claude.json)을 찾아 아래와 같이 수동 실행된 서버의 주소를 명시합니다:

{
  "mcpServers": {
    "agy": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

구성 요소 실행 방법

A. 테스트 클라이언트 (Web UI) 구동

테스트용 웹 앱을 실행하려면 다음 명령어를 기동합니다:

# macOS/Linux에서 가상환경이 켜진 상태 또는 전체 경로로 실행:
agy-mcp-env/bin/python test-mcp-client/app.py

# Windows PowerShell에서 실행:
.\agy-mcp-env\Scripts\python.exe test-mcp-client\app.py

Open http://127.0.0.1:5001을 열어줍니다. 실시간으로 8000번 포트의 활성 SSE 서버 상태를 감지하며, 서버가 꺼져 있을 경우 자동으로 백그라운드 STDIO 서브프로세스로 기동해 연동합니다!

B. MCP 서버 수동 구동 (단독 실행)

독립적인 SSE 수신 포트(8000번)로 서버를 단독 구동하려는 경우:

agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000

참고 자료

• Google Antigravity Python SDK