antigravity-bridge 1.2.1

Lightweight MCP server bridging Claude Code to Antigravity AI via official CLI

Antigravity Bridge

A lightweight MCP (Model Context Protocol) server that enables AI coding assistants to interact with Antigravity AI through the official CLI. Zero API costs, stateless architecture, minimal dependencies. Production-ready with comprehensive CI/CD automation.

Features

• Direct Antigravity CLI Integration: Zero API costs using the official agy CLI
• Four MCP Tools: Basic queries, file analysis, web search, and model listing
• Rich MCP Surface: Structured (Pydantic) tool outputs, proper ToolError reporting, tool annotations + titles, client-side logging via Context, server instructions, a config://settings resource, reusable prompts, and model argument completion
• Stateless Operation: No sessions, caching, or complex state management (optional conversation continuation is caller-driven)
• Production Ready: Async, non-blocking execution with retries, health checks, structured logging, and metrics; runs agy --print under a pseudo-TTY to work around upstream headless-hang bug #318
• Secure by Default: Path containment, directory allowlisting, query + model validation, and binary-file guards; permission-skipping is opt-in
• Minimal Dependencies: Only requires mcp>=1.0.0 and Antigravity CLI
• Easy Deployment: Support for both uvx and traditional pip installation
• Universal MCP Compatibility: Works with Claude Code, Cursor, VS Code, Windsurf, Cline, Void, Cherry Studio, Augment, Roo Code, Zencoder, and any MCP-compatible client
• Modern Python: Python 3.10+ with type hints and pathlib

Prerequisites

Install the Antigravity CLI:

# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

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

# Verify installation
agy --version

Authentication is handled internally by Antigravity — no separate login command needed.

Installation

Recommended: PyPI with uvx

claude mcp add antigravity-bridge -s user -- uvx antigravity-bridge

From PyPI

pip install antigravity-bridge
claude mcp add antigravity-bridge -s user -- uvx antigravity-bridge

From Source

git clone https://github.com/FojleRabbiRabib/Antigravity-Bridge.git
cd antigravity-bridge
pip install -e .

# Development mode
claude mcp add antigravity-bridge-dev -s user -- python3 -m src

Configuration

Environment Variables

All configuration is done through environment variables prefixed with ANTIGRAVITY_BRIDGE_:

Variable	Default	Description
ANTIGRAVITY_BRIDGE_TIMEOUT	600	Global timeout override (seconds)
ANTIGRAVITY_BRIDGE_DEFAULT_TIMEOUT	600	Module-level default timeout
ANTIGRAVITY_BRIDGE_SKIP_PERMISSIONS	true	Add --dangerously-skip-permissions. Default on so consults/investigations run (agy print mode can't prompt for approvals; without it a non-trivial query bails after planning). Set false + ANTIGRAVITY_BRIDGE_ALLOWED_DIRS to lock down.
ANTIGRAVITY_BRIDGE_SANDBOX	false	Add --sandbox for restricted execution
ANTIGRAVITY_BRIDGE_MODEL	(agy default)	Default model override for consult tools
ANTIGRAVITY_BRIDGE_ALLOWED_DIRS	(empty = unrestricted)	Comma/colon-separated directory allowlist
ANTIGRAVITY_BRIDGE_HEALTH_CHECK	true	Cached one-time agy --version preflight
ANTIGRAVITY_BRIDGE_FORCE_TTY	false	Run agy --print over plain pipes by default (reliable on current agy). Set true to force a pseudo-TTY only if your agy build hangs headless (upstream bug #318, agy ≤1.0.6 / Windows)
ANTIGRAVITY_BRIDGE_ALIGN_PRINT_TIMEOUT	true	Pass --print-timeout so agy --print aborts on its own when the bridge timeout elapses
ANTIGRAVITY_BRIDGE_MAX_RETRIES	2	Retries on transient failures (0 disables)
ANTIGRAVITY_BRIDGE_RETRY_BACKOFF_BASE	0.5	Exponential backoff base (seconds)
ANTIGRAVITY_BRIDGE_MAX_QUERY_LENGTH	100000	Max prompt length (chars)
ANTIGRAVITY_BRIDGE_LOG_LEVEL	INFO	Logging level
ANTIGRAVITY_BRIDGE_LOG_FORMAT	text	text or json (structured)
ANTIGRAVITY_BRIDGE_MAX_INLINE_FILE_COUNT	30	Max files in inline mode
ANTIGRAVITY_BRIDGE_MAX_INLINE_TOTAL_BYTES	1048576 (1MB)	Max total inline payload
ANTIGRAVITY_BRIDGE_MAX_INLINE_FILE_BYTES	524288 (512KB)	Max per-file inline size
ANTIGRAVITY_BRIDGE_INLINE_HEAD_BYTES	65536 (64KB)	Head chunk for truncated files
ANTIGRAVITY_BRIDGE_INLINE_TAIL_BYTES	32768 (32KB)	Tail chunk for truncated files

Security note: ANTIGRAVITY_BRIDGE_SKIP_PERMISSIONS defaults to true so consults/investigations actually execute — agy's print mode cannot prompt for tool approvals, and without it a non-trivial query bails after planning (returns only the "I will…" narration). To lock the server down, set it to false and configure the allowlist (ANTIGRAVITY_BRIDGE_ALLOWED_DIRS).

Timeout example:

claude mcp add antigravity-bridge -s user --env ANTIGRAVITY_BRIDGE_TIMEOUT=180 -- uvx antigravity-bridge

Available Tools

agy_consult

Direct CLI bridge for simple queries.

Parameters:

• query (string, required): The question or prompt to send to Antigravity
• directory (string, required): Working directory for the query
• timeout_seconds (int, optional): Override execution timeout for this request
• model (string, optional): Model override (e.g. "gemini-3.5-flash")
• add_dirs (list, optional): Extra directories to attach to the workspace
• conversation_id (string, optional): Resume a specific conversation by ID
• continue_last (bool, optional): Continue the most recent conversation

Example:

agy_consult(query="What authentication patterns are used?", directory="/path/to/project")

agy_consult_with_files

CLI bridge with file attachments for detailed analysis.

Parameters:

• query (string, required): The question or prompt
• directory (string, required): Working directory
• files (list, required): List of file paths relative to the directory
• timeout_seconds (int, optional): Override execution timeout
• mode (string, optional): "inline" (default) or "at_command"
• model (string, optional): Model override
• add_dirs (list, optional): Extra directories to attach to the workspace
• conversation_id (string, optional): Resume a specific conversation by ID
• continue_last (bool, optional): Continue the most recent conversation

File Modes:

• inline — streams truncated file snippets directly in the prompt (binary files are skipped)
• at_command — emits @path directives so Antigravity CLI resolves files itself

Example:

agy_consult_with_files(
    query="Review these auth files for security issues",
    directory="/path/to/project",
    files=["src/auth.py", "src/middleware.py"],
    mode="at_command"
)

agy_web_search

Queries with web search context. Best-effort — the model decides when to search.

Parameters:

• query (string, required): Search query or question
• directory (string, required): Working directory for command execution
• timeout_seconds (int, optional): Override execution timeout
• model (string, optional): Model override
• add_dirs (list, optional): Extra directories to attach to the workspace
• conversation_id (string, optional): Resume a specific conversation by ID
• continue_last (bool, optional): Continue the most recent conversation

Example:

agy_web_search(query="latest Python 3.13 features")

agy_list_models

List the models available to the Antigravity CLI (wraps agy models).

Parameters: none

Example:

agy_list_models()

Structured Tool Outputs

Every tool returns a structured Pydantic object instead of a raw string:

{
  "success": true,
  "output": "The response from Antigravity...",
  "model": "Claude Opus 4.6 (Thinking)",
  "warnings": [],
  "duration_ms": 12450.5
}

If a tool execution fails (e.g., timeout, invalid directory, authentication issue), the bridge raises a proper ToolError rather than returning an error string, enabling clients to handle failures natively.

Resources & Prompts

Alongside tools, the bridge exposes standard MCP resources and prompts to the client:

Resources

• config://settings — Exposes the server's effective settings, directory allowlist, version, and default parameters in JSON format.

Reusable Prompts

• investigate_project — Builds a thorough, assumption-free prompt to investigate a workspace directory.
• code_review — Builds a focused code-review prompt seeking correctness, robustness, and security issues.
• consult — Formats a query to include an autocompleted model parameter.

Multi-Client Support

Antigravity Bridge works with any MCP-compatible AI coding assistant. The server implementation is identical across clients — only the configuration differs.

Claude Code

claude mcp add antigravity-bridge -s user -- uvx antigravity-bridge

Cursor

Global (~/.cursor/mcp.json):

{
  "mcpServers": {
    "antigravity-bridge": {
      "command": "uvx",
      "args": ["antigravity-bridge"]
    }
  }
}

VS Code

Configuration (.vscode/mcp.json):

{
  "servers": {
    "antigravity-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["antigravity-bridge"]
    }
  }
}

Windsurf

{
  "mcpServers": {
    "antigravity-bridge": {
      "command": "uvx",
      "args": ["antigravity-bridge"]
    }
  }
}

Cline (VS Code Extension)

1. Click MCP Servers in top navigation
2. Select Installed tab → Advanced MCP Settings
3. Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "antigravity-bridge": {
      "command": "uvx",
      "args": ["antigravity-bridge"]
    }
  }
}

Void

Settings → MCP → Add MCP Server

{
  "command": "uvx",
  "args": ["antigravity-bridge"]
}

Cherry Studio

Settings → MCP Servers → Add Server

• Name: antigravity-bridge
• Type: STDIO
• Command: uvx
• Arguments: ["antigravity-bridge"]

Augment

Click hamburger menu → Settings → Tools → + Add MCP

• Command: uvx antigravity-bridge
• Name: Antigravity Bridge

Roo Code

Settings → MCP Servers → Edit Global Config

{
  "mcpServers": {
    "antigravity-bridge": {
      "command": "uvx",
      "args": ["antigravity-bridge"]
    }
  }
}

Zencoder

Zencoder menu → Tools → Add Custom MCP

{
  "command": "uvx",
  "args": ["antigravity-bridge"]
}

Architecture

Design Principles

• CLI-First: Direct subprocess calls to agy --print
• Stateless: Each tool call is independent with no session state
• Adaptive Timeout: Defaults to 600 seconds, overridable per request or via env var
• Attachment Guardrails: Inline mode enforces byte/quantity caps; @ mode delegates to Antigravity CLI
• Fail-Fast: Clear error messages with simple error handling
• Zero Extra Dependencies: Only mcp>=1.0.0 beyond the Antigravity CLI

Module Structure

src/
├── __init__.py        # Package entry point, single-source version
├── __main__.py        # Module execution entry point
├── config.py          # Validated Settings + environment variables
├── security.py        # Path containment, allowlist, query/binary validation
├── files.py           # File handling (inline, @-command, truncation)
├── command.py         # Typed agy argv builder (AgyCommand)
├── cli.py             # Async subprocess execution, retry, health check
├── observability.py   # Structured logging (text/JSON), request IDs, metrics
└── tools.py           # MCP tool definitions (FastMCP, async)

File Handling Safeguards

• Inline transfers cap at 512KB per file and 1MB per request
• Oversized files are truncated to head/tail snippets with warnings
• Tune caps via ANTIGRAVITY_BRIDGE_MAX_INLINE_* env vars
• Use mode="at_command" for larger payloads

Development

# Install in development mode
pip install -e .

# Run tests
pytest

# Run MCP server directly
python3 -m src

# Verify CLI availability
agy --version

Build & Distribution

# Clean build
rm -rf dist/ build/ *.egg-info

# Build package
uvx --from build pyproject-build

# Verify build
pip install dist/*.whl
python3 -c "import src; print(f'v{src.__version__}')"

Troubleshooting

Error	Solution
"Antigravity CLI not found"	curl -fsSL https://antigravity.google/cli/install.sh | bash
"Authentication required"	Verify Antigravity authentication
"Health check failed"	Run agy --version; verify install/auth, or set ANTIGRAVITY_BRIDGE_HEALTH_CHECK=false
"Timed out after X seconds"	Increase timeout or simplify query
"Directory does not exist"	Use absolute paths or verify directory
"Directory not in allowlist"	Add it to ANTIGRAVITY_BRIDGE_ALLOWED_DIRS (or leave empty for unrestricted)
"No files provided"	Provide at least one valid file path
"Unsupported files mode"	Use "inline" or "at_command"
"Extra inputs are not permitted"	The call passed an argument the tool doesn't accept. Tool schemas forbid unknown params (additionalProperties: false) — drop it and use only the documented parameters.
"Skipped binary file" / "outside working directory"	Expected guards — inline mode skips binaries and path escapes

Contributing

See CONTRIBUTING.md for development guidelines.

License

Apache 2.0 — see LICENSE.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions