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.

Related MCP server: agy-mcp

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.

* 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