Antigravity MCP Server

Run Google's Antigravity/Gemini CLI (agy) as an MCP server — a multi-model conductor/executor for AI agents.

What & why

A Model Context Protocol server that exposes the Antigravity CLI (agy, Google's Gemini agent) as a set of tools usable from Claude Code, Claude Desktop, Cursor, and Windsurf.

The animating idea is cost discipline through model tiering: a frontier model (Claude) acts as the conductor, and cheaper Gemini (agy) is the executor it offloads bulky, token-heavy work to — web research, codebase indexing, cross-model review, commit messages. The heavy output stays on disk and in the cheap model's context; the conductor ingests only short digests, so its own context stays lean and its bill stays low. Tiers (flash → pro → cross-family sonnet/opus/gpt-oss) let you dial cost against quality per task.

Architecture

        ┌─────────────────────────────┐
        │   Conductor (Claude)        │   plans, verifies, keeps context lean
        │   via any MCP client        │
        └──────────────┬──────────────┘
                       │  MCP tool calls (stdio)
        ┌──────────────▼──────────────┐
        │   Antigravity MCP server    │   antigravity_mcp/  (this repo)
        │   FastMCP · 13 tools/3 prompts
        └──────────────┬──────────────┘
                       │  subprocess  (prompt via stdin / tempfile path)
        ┌──────────────▼──────────────┐
        │   agy CLI  →  Gemini        │   Executor: web search, file reads, generation
        └──────────────┬──────────────┘
                       │  detached workers write here
        ┌──────────────▼──────────────┐
        │  $ANTIGRAVITY_JOBS (~/.antigravity-jobs)
        │  per-job dirs: out · err · rc · subreport.md · manifest.json
        └─────────────────────────────┘

• Single FastMCP server. Every tool is a @mcp.tool()-decorated function; every prompt is @mcp.prompt(). All tools shell out to agy via subprocess, guarding on shutil.which("agy") first.
• Model tiering. model_for_tier() maps a semantic tier to a concrete Gemini/cross-family model — the one place to update when Antigravity renames models.
• Filesystem-backed background jobs. Long jobs run as detached processes that redirect to out/err and write their exit code to rc. State is reconstructed purely from those files, so jobs survive the MCP server restarting.
• Parallel fan-out pipelines. A shared _start_batch primitive launches one worker per sub-question (research) or per aspect (review). Workers write full reports to disk and print only a short digest; batch-generic collectors gather them.
• Large inputs never hit the command line. Prompts pipe via stdin; big diffs/files are written to a tempfile and only the path is passed, dodging OS argument-length limits.

A fuller, auto-generated breakdown lives in ARCHITECTURE.md — itself produced by this server's own index_code tool (see Dogfooding below).

Quickstart

Prerequisites

• Antigravity CLI (agy) installed and authenticated (run agy once interactively to sign in).
• Python ≥ 3.12
• uv

Add to Claude Code

mcp add antigravity-server uv run --directory /absolute/path/to/this/repo main.py

Add to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "antigravity": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/this/repo", "main.py"]
    }
  }
}

Run the server directly

uv run main.py          # stdio transport

Try the pipeline (copy-paste)

examples/deep_research_example.py drives the fan-out research tools end-to-end (fan out → poll → collect digests) against the cheap flash-lo tier:

uv run python examples/deep_research_example.py

Uses web search, so it spends real Antigravity quota.

Tools

13 tools across four groups, plus 3 orchestration prompts.

Tool	Group	What it does
delegate_to_antigravity	Delegation	Run a synchronous task on agy; targeted quota/auth/timeout error hints.
start_background_job	Delegation	Dispatch a long-running task to a detached process; returns a job_id.
check_job_status	Delegation	Reconstruct a background job's status/output from its on-disk files.
propose_research_questions	Deep research	Cheap pre-flight: draft clarifying questions + sub-questions to sharpen a brief before spending quota.
research_fanout	Deep research	Launch one parallel grounded-research worker per sub-question (web search → report on disk + digest).
research_status	Deep research *	Aggregate progress of every worker in a batch.
collect_digests	Deep research *	Gather workers' short digests plus on-disk report paths, keeping context lean.
propose_design_questions	Architect/build	The grill: draft a requirements interview + candidate requirements for a build/improvement.
review_fanout	Architect/build	Launch one parallel code-review worker per aspect (architecture, security, tests, …).
draft_design_doc	Architect/build	Have agy draft a full design doc (with work packages) from on-disk batches + a verified brief.
cross_model_review	Code & git	Independent diff review — use tier='gpt-oss'/'sonnet' for a different model family than the author.
auto_git_commit	Code & git	Stage, generate a conventional commit message, commit, and optionally push.
index_code	Code & git	Distill directories/files into an architectural index without pulling raw code into the conductor's context.

* research_status and collect_digests are batch-generic — they read any batch's sub_NN/subreport.md + manifest.json, so the review pipeline reuses them unchanged.

Prompts: antigravity_research_recipe (deep-research recipe), antigravity_build_recipe (Spec-Driven Requirements → Design → Tasks → Implement loop), and antigravity_workflow (the core conductor/executor cost-discipline rules).

Model tiers

flash · flash-med · flash-lo · pro (default for research/review) · pro-lo · and cross-family sonnet · opus · gpt-oss. Tier→model resolution is centralised in model_for_tier(); run agy models for the live list.

Two pipelines

• Deep research — research_fanout → research_status → collect_digests. Claude plans and adversarially verifies; agy does the grounded web legwork in parallel.
• Architect/build — propose_design_questions → review_fanout/research_fanout → draft_design_doc. A Spec-Driven loop for creating or improving codebases; agy drafts, Claude refines and drives implementation.

Companion Claude Code skills (/deep-research, /grill-me-research, /architect) orchestrate these pipelines end-to-end. They live in the user's ~/.claude/skills/ and are not shipped in this repo — the server and its @mcp.prompt() recipes are self-contained without them.

Dogfooding

This repo was tidied up for release using its own tools — a nice end-to-end proof that they work:

• index_code distilled the package into ARCHITECTURE.md.
• cross_model_review gave an independent second-model pass over the release diff.

Testing

uv run python test_offline.py       # fast, offline, no `agy`, no quota (pure-Python helper tests)
uv run python smoke_test_manual.py  # manual end-to-end smoke test — invokes real `agy`, spends quota

Caveats

• This is a thin wrapper around the external agy CLI: it doesn't call Gemini directly, so it inherits agy's auth and quota. Tools return human-readable error strings (never exceptions) with remediation tips.
• It's a personal project, not an official Google or Anthropic product.
• Several tools (cross_model_review, auto_git_commit, index_code, the fan-out workers) run agy with --dangerously-skip-permissions because they need autonomous file/web access. Point them at code you trust.
• Model tier names track Antigravity's current model lineup and may drift as Google renames models — update model_for_tier() when they do.

License

MIT © James Zoryk