Content
# 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)
- [한국어 문서](#한국어-문서)
---
# English Documentation
> [!WARNING]
> **Prototype Release Notice**
> This repo is a demo and prototype of the Antigravity SDK. Thorough review is required before applying it to a production environment.
## 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.
---
## 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).
```mermaid
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:
```bash
gcloud auth application-default login
```
### 3. Initialize Python Virtual Environment
Set up a clean virtual environment and install dependencies:
```bash
# 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:
```json
{
"GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
"GCP_LOCATION": "<YOUR_GCP_LOCATION>",
"MODEL": "gemini-3.5-flash"
}
```
> [!NOTE]
> Replace `<YOUR_GCP_PROJECT_ID>` with your actual Google Cloud Project ID, and `<YOUR_GCP_LOCATION>` with your desired region (e.g., `us-central1` or `us-east4`).
---
## 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:
```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>"
}
}
}
}
```
> [!IMPORTANT]
> - Replace `<WORKSPACE_ABSOLUTE_PATH>` with the full absolute path of this workspace directory (e.g. `C:\\Users\\yourname\\projects\\antigravity-mcp-server`).
> - Be sure to use **double backslashes (`\\`)** in paths to escape them correctly in JSON.
#### B. macOS / Linux Setup
Locate your Claude Code global configuration file (typically `~/.claude.json`).
Update or create the file with the following configuration:
```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>"
}
}
}
}
```
> [!IMPORTANT]
> - Replace `<WORKSPACE_ABSOLUTE_PATH>` with the full absolute path of this workspace directory (e.g. `/Users/yourname/projects/antigravity-mcp-server`).
---
### 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:**
```bash
agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
```
* **On Windows:**
```bash
.\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:
```json
{
"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:
```bash
# 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](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:
```bash
agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
```
## References
- [Google Antigravity Python SDK Repository](https://github.com/google-antigravity/antigravity-sdk-python)
---
---
# Tool List
## System Architecture and Multi-Agent Routing
This workspace adopts a **Multi-Agent Routing** structure between the upper coordinator (Claude Code) and the lower executor (Antigravity Agent). The overall interaction and communication structure is as follows:
```mermaid
graph TD
CC["Claude Code CLI"] -->|"SSE / STDIO"| MS["AGY MCP Server"]
TWC["Test Web App"] -->|"SSE / STDIO"| MS
MS -->|"SDK call and initialization"| Agent["Antigravity Agent"]
Agent -->|"Gemini API call"| Vertex["Gemini Enterprise Agent Platform"]
Agent -.->|"Record storage"| Log["Telemetry Log<br>(thinking.log)"]
TWC -.->|"Log parsing"| 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 and Multi-Agent Routing Principles
1. **Claude Code as the Upper Orchestrator (Top-Level Router)**
When users submit tasks with keywords such as `antigravity`, `agy`, `gemini`, etc., Claude Code becomes the top-level mediator. Instead of blindly performing tasks itself, it searches for the most suitable dedicated MCP tool through semantic keyword matching.
2. **Cohesive Semantic Synonym Routing**
The docstrings of FastMCP tools (`agy_task`, `agy_code_review`) are designed with detailed semantic keywords, allowing Claude Code to dynamically detect and delegate tasks to the corresponding MCP server. This enables stable resource control from a single entry point without needing to run multiple servers individually.
3. **Autonomous Delegation to Lower Specialized Agents (Antigravity Agent Execution)**
Upon receiving a delegation request (JSON-RPC), the AGY MCP server dynamically creates a lower specialized agent (Antigravity Agent). This agent directly utilizes the high-performance inference capabilities of the Google Cloud Gemini Enterprise Agent Platform to perform local file editing and advanced code reviews.
4. **Telemetry Logs**
The inference process generated during agent execution is stored in a project directory outside path (`~/.gemini/antigravity/thinking.log`).
---
## Installation and Server Setup Guide
This is a step-by-step guide for developers to easily follow, supporting Windows, macOS, and Linux.
### 1. Pre-Installation Requirements
- **Python 3.10 or higher** must be installed on the system.
- The **Google Cloud SDK (`gcloud` CLI)** must be installed and logged in.
- A **Google Cloud project** with the **Gemini Enterprise Agent Platform API** enabled is required.
### 2. Google Cloud Authentication Registration
Configure the local terminal environment to have Google Cloud permissions to connect to the Gemini Enterprise Agent Platform and Gemini models:
```bash
gcloud auth application-default login
```
### 3. Python Virtual Environment Initialization and Dependency Installation
Create a new virtual environment and install the necessary library packages for the project:
```bash
# Create virtual environment
python -m venv agy-mcp-env
# Activate virtual environment
# macOS/Linux environment:
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. GCP Environment Variables and Configuration File Creation
Create a new configuration file `agy-mcp-config.json` in the `mcp-server/` directory to declare the GCP resources the server will access:
```json
{
"GCP_PROJECT": "<YOUR_GCP_PROJECT_ID>",
"GCP_LOCATION": "<YOUR_GCP_LOCATION>",
"MODEL": "gemini-3.5-flash"
}
```
> [!NOTE]
> Replace `<YOUR_GCP_PROJECT_ID>` with your actual Google Cloud Project ID, and `<YOUR_GCP_LOCATION>` with your region (e.g., `us-central1`, `us-east4`, etc.).
---
## Claude Code Integration Method
There are two options to integrate this server with **Claude Code**, depending on the runtime configuration.
### Option 1: STDIO Communication Mode (Recommended)
In this mode, Claude Code directly runs the Python MCP server as a background subprocess and communicates with it when needed.
#### A. Windows Environment Setup (PowerShell)
Find the global configuration file of Claude Code (usually `%USERPROFILE%\.claude.json` or `C:\Users\<username>\.claude.json`) and modify or create it as follows:
```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>"
}
}
}
}
```
> [!IMPORTANT]
> - Replace `<WORKSPACE_ABSOLUTE_PATH>` with the **absolute path** of the current project workspace folder (e.g., `C:\\Users\\yourname\\projects\\antigravity-mcp-server`).
> - Ensure backslashes in the path are **doubled (`\\`)** for correct escape processing.
#### B. macOS / Linux Environment Setup
Find the global configuration file of Claude Code (usually `~/.claude.json`) and modify or create it as follows:
```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>"
}
}
}
}
```
> [!IMPORTANT]
> Replace `<WORKSPACE_ABSOLUTE_PATH>` with the **absolute path** of the current project workspace folder (e.g., `/Users/yourname/projects/antigravity-mcp-server`).
---
### Option 2: Server Mode (SSE Communication Mode)
In this mode, run the MCP server as a separate, independent terminal runtime, and have Claude Code connect via Server-Sent Events (SSE) protocol.
#### 1. Independent Server Execution
Open a separate terminal window and run the following command to start the persistent server on port `8000`:
* **macOS / Linux environment:**
```bash
agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
```
* **Windows environment:**
```bash
.\agy-mcp-env\Scripts\python.exe mcp-server\server.py --transport sse --port 8000
```
#### 2. Claude Code Configuration File Registration
Find the Claude Code global configuration file (`~/.claude.json` or `%USERPROFILE%\.claude.json`) and specify the manually run server address as follows:
```json
{
"mcpServers": {
"agy": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
```
---
## Component Execution Method
### A. Test Client (Web UI) Execution
To run the test web app, execute the following command:
```bash
# On macOS/Linux with virtual environment activated or using full path:
agy-mcp-env/bin/python test-mcp-client/app.py
# On Windows PowerShell:
.\agy-mcp-env\Scripts\python.exe test-mcp-client\app.py
```
Open [http://127.0.0.1:5001](http://127.0.0.1:5001) to access it. It detects the active SSE server status on port 8000 in real-time and automatically starts the background STDIO subprocess for integration if the server is down!
### B. MCP Server Manual Execution (Independent Execution)
To run the server independently with an SSE receiving port (port 8000):
```bash
agy-mcp-env/bin/python mcp-server/server.py --transport sse --port 8000
```
## References
- [Google Antigravity Python SDK](https://github.com/google-antigravity/antigravity-sdk-python)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available