Skip to main content
Glama
Antigravity MCP Server

Antigravity MCP Server

by JamesZor

Antigravity MCP Server

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

License: MIT Python 3.12+ MCP

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-headless-bridge MCP server

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

18 tools across five groups, plus 4 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.

list_agy_skills

Science skills

Catalog the skills installed in agy (name, plugin, one-liner). Zero quota — reads the filesystem.

check_science_credentials

Science skills

Report which API keys each skill wants and which are present in ~/.env. Never prints a value.

propose_science_plan

Science skills

Cheap pre-flight: draft sub-questions already mapped to the right databases, plus a clarifying interview.

delegate_with_skills

Science skills

Run ONE task pinned to named skills, in an isolated workspace.

science_fanout

Science skills *

Launch one parallel worker per sub-question, each pinned to real database CLIs.

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 and science pipelines reuse them unchanged.

Prompts: antigravity_research_recipe (deep-research recipe), antigravity_build_recipe (Spec-Driven Requirements → Design → Tasks → Implement loop), antigravity_science_recipe (primary-source science research), 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.

Three 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.

  • Science (primary sources) — propose_science_plan → science_fanout → research_status → collect_digests. See below.

Science skills (primary-source research)

agy can load agent skills, notably Google DeepMind's science-skills bundle — ~39 skills wrapping arXiv, OpenAlex, PubMed, UniProt, PDB, ChEMBL, ClinVar, gnomAD, AlphaFold, AlphaGenome, ClinicalTrials.gov and more, each a rate-limited CLI over the real API.

This matters because research_fanout is web search, and web search will hand you a plausible-looking DOI that does not exist. These skills call the actual databases and are forbidden to fabricate identifiers. science_fanout is the primary-source counterpart — same cost profile (agy works, Claude reads digests), but every ID it returns came from a real API call.

Despite the name, this is not biomedical-only. Two families live here:

  • All-discipline literature — literature-search-arxiv covers every arXiv category (statistics, maths, CS, physics, economics, quant-finance) and literature-search-openalex indexes all scholarly work in every field, with real DOIs and citation counts. A literature scan on Bayesian count models or transformer architectures is squarely in scope.

  • Domain databases — PubMed, UniProt, PDB, ChEMBL, ClinVar, gnomAD, AlphaFold, ClinicalTrials.gov, for primary biomedical and chemical records.

Rule of thumb: /science-research when you need citations you can trust; /deep-research when you need breadth across the open web (news, blogs, docs, market scans). For a pure derivation, neither — just do the maths.

Setup: install the bundle in Antigravity (Settings → Customizations → Build with Google Plugins → Science). No API key is needed to start — most skills work keyless at lower rate limits, and check_science_credentials() tells you exactly which keys would help and how to add them safely.

Two design notes worth knowing, since they're not obvious:

  • agy has no --skill flag. It auto-loads every installed skill's description and triggers on prompt content, so pinning a worker to a skill means naming it in the prompt and handing over its absolute path (skill_preamble() in agy.py).

  • The bundled credentials skill tells an agent to halt and prompt the user when a key is missing. A detached worker has no user, so it would stall until timeout. skill_preamble() resolves credentials up front and explicitly overrides that protocol; a genuinely required key (only AlphaGenome has one) refuses the launch instead.

Each worker's DATA_STATUS: OK | PARTIAL | BLOCKED line is the health signal that catches the one failure mode that looks like success — a worker quietly answering from memory instead of querying.

Companion Claude Code skills

/deep-research, /grill-me-research and /architect orchestrate the first two pipelines. They live in the user's ~/.claude/skills/ and are not shipped here — the server and its @mcp.prompt() recipes are self-contained without them.

The science pipeline's skill is shipped, in skills/science-research/. Install it with:

cp -r skills/science-research ~/.claude/skills/

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
uv run python smoke_test_science.py  # manual science-pipeline smoke test — needs the science plugin, 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

Available Tools

13 tools
auto_git_commitA
Automatically stage, generate a commit message using Antigravity, commit, and optionally push.
Use this to offload boring token-wasting git operations from the frontier model.

Args:
    repo_path: The absolute path to the git repository.
    push: Whether to 'git push' after committing.
    stage_all: Whether to 'git add .' before generating the commit. If False, only uses currently staged changes.

Inputs: repo_path (required), push, stage_all. Returns: result

check_job_statusA
Check the status and retrieve the output of a background job.

Args:
    job_id: The ID of the job to check.

Inputs: job_id (required). Returns: result

collect_digestsA
Gather the stdout digests from a finished research batch (NOT the full reports).

Keeps Claude's context lean: returns each worker's short digest plus the on-disk path
to its full report. Read individual subreport.md files only when a claim needs deeper
verification.

Args:
    batch_id: The batch ID returned by research_fanout.
    include_stderr: If True, also include each worker's stderr (for debugging failures).

Inputs: batch_id (required), include_stderr. Returns: result

cross_model_reviewB
Get an independent cross-model review of a code diff using Antigravity.

Tip: set tier='gpt-oss' or 'sonnet' for a genuinely different model family than the
author, which surfaces blind spots a same-family reviewer would share.

Args:
    diff: The git diff or code changes to review.
    adversarial: If True, challenges design decisions and trade-offs rather than just finding line-level bugs.
    tier: Model tier. Default is 'pro' for deeper reasoning.

Inputs: diff (required), tier, adversarial. Returns: result

delegate_to_antigravityA
Delegate a well-scoped subtask to Antigravity (agy/Gemini) under cost discipline, then verify.

Args:
    prompt: The task prompt to send to Antigravity.
    tier: Model tier (flash, flash-med, flash-lo, pro, pro-lo, sonnet, opus, gpt-oss). Default is flash.
    dirs: Workspaces to attach so agy reads real files.
    yolo: Auto-approve all tool permissions (DANGEROUS). Required for web search.
    sandbox: Run agent with terminal sandbox restrictions.
    continue_session: Resume the most recent agy conversation (stateful).
    conversation_id: Resume a specific agy conversation by ID (stateful).
    timeout: Print-mode timeout, e.g., '10m'. Default is '5m'.

Inputs: prompt (required), dirs, tier, yolo, +4 more. Returns: result

draft_design_docA
Have Antigravity draft a structured design document (with work packages) from on-disk batches.

The synthesis step of the Architect pipeline. agy reads the digests/subreports from the given
review + research batch dirs PLUS the orchestrator's verified `brief`, and drafts a full design
doc to `out_path`. Returns only a short digest — the orchestrator (Claude) then reads the file,
verifies claims, and edits it in place. This is the 'agy drafts, Opus refines' gate.

Args:
    goal: The project goal the design serves.
    brief: Claude's verified findings / requirements (the trustworthy synthesis so far).
    batch_ids: review_fanout / research_fanout batch IDs whose reports agy should read.
    out_path: Absolute path to write the design doc (e.g. <repo>/design.md).
    tier: Model tier for the draft (default 'pro').

Inputs: goal (required), brief (required), out_path (required), batch_ids (required), +1 more. Returns: result

index_codeA
Reads specific directories or files using Antigravity's massive context window and returns a distilled architectural index.
Use this to quickly understand a subset of a codebase (or a whole repo) without pulling all the raw files into the frontier model's context window.

Args:
    paths: A list of absolute paths to directories or files to index.
    focus: What to focus the index on (e.g., 'general architecture', 'database schemas', 'API routes'). Default is 'general architecture'.
    out_path: Optional absolute path to also persist the index to (e.g. '<repo>/docs/ARCHITECTURE.md') so it survives for incremental reuse instead of living only in the caller's context.

Inputs: paths (required), focus, out_path. Returns: result

propose_design_questionsA
Draft clarifying questions and candidate requirements to sharpen a build/improvement brief.

The first step of the Architect pipeline (the *grill*). Mirrors propose_research_questions
but for software projects: offloads brainstorming the requirements interview to a cheap
agy model. Returns clarifying questions (each with answer options) the orchestrator should
put to the user, plus a draft set of requirements. The orchestrator asks the user, refines,
and writes requirements.md before spending quota on a code review or design doc.

Returns JSON: {"clarifying_questions": [{"question", "why", "options": [...]}],
"draft_requirements": [...]}. Falls back to raw text if the model returns non-JSON.

Args:
    goal: The project goal — what to build or improve.
    repo_path: Optional path to an existing codebase being improved (gives the model context).
    context: Optional extra context (users, constraints, deadline, what already exists).
    tier: Model tier for the brainstorm (default 'flash' — this is a cheap task).

Inputs: goal (required), tier, context, repo_path. Returns: result

propose_research_questionsA
Draft clarifying questions and candidate sub-questions to sharpen a research brief.

Run this BEFORE research_fanout. It offloads brainstorming the interview to a cheap
agy model: it returns clarifying questions (each with suggested answer options) that the
orchestrator should put to the user, plus a draft set of sub-questions. The orchestrator
then asks the user, refines the brief, and only then spends quota on research_fanout.

Returns JSON: {"clarifying_questions": [{"question", "why", "options": [...]}],
"draft_subquestions": [...]}. Falls back to raw text if the model returns non-JSON.

Args:
    topic: The research topic to interrogate.
    context: Optional extra context (audience, deadline, what's already known).
    tier: Model tier for the brainstorm (default 'flash' — this is a cheap task).

Inputs: topic (required), tier, context. Returns: result

research_fanoutA
Launch parallel grounded-research workers, one detached Antigravity (agy) job per sub-question.

This is the fan-out half of a deep-research pipeline. Each worker web-searches its
sub-question, writes a full markdown report to a file, and prints a short digest to
stdout. Reports stay on disk so Claude's context stays lean — poll with
research_status(batch_id) and gather with collect_digests(batch_id).

Args:
    topic: The overarching research topic (gives each worker shared context).
    subquestions: One focused sub-question per worker. Each launches a parallel job.
    tier: Model tier for every worker (default 'pro' = Gemini 3.1 Pro High).
    timeout: Per-worker print-mode timeout, e.g., '10m'.

Inputs: topic (required), subquestions (required), tier, timeout. Returns: result

research_statusA
Report aggregate status of every worker in a research batch.

Args:
    batch_id: The batch ID returned by research_fanout.

Inputs: batch_id (required). Returns: result

review_fanoutA
Launch parallel codebase-review workers, one detached Antigravity (agy) job per aspect.

The code analog of research_fanout. Each worker reads the repo (via --add-dir) and reviews
ONE aspect (architecture, security, performance, tests, etc.), writes a full markdown report
to disk, and prints a short digest to stdout. Reports stay on disk so Claude's context stays
lean — poll with research_status(batch_id) and gather with collect_digests(batch_id), exactly
as for a research batch (the collectors are batch-generic).

Args:
    repo_path: Absolute path to the codebase to review.
    aspects: One review aspect per worker. Defaults to a 7-aspect standard sweep.
    goal: Optional improvement goal to focus the review (e.g. 'prepare for multi-tenant SaaS').
    tier: Model tier for every worker (default 'pro' = Gemini 3.1 Pro High).
    timeout: Per-worker print-mode timeout, e.g., '10m'.

Inputs: repo_path (required), goal, tier, aspects, +1 more. Returns: result

start_background_jobA
Start a long-running Antigravity (agy/Gemini) task in the background.
Returns a job_id that can be used to check status.

Args:
    prompt: The task prompt to send to Antigravity.
    tier: Model tier (flash, flash-med, flash-lo, pro, pro-lo, sonnet, opus, gpt-oss). Default is flash.
    dirs: Workspaces to attach so agy reads real files.
    yolo: Auto-approve all tool permissions (DANGEROUS). Required for web search.
    sandbox: Run agent with terminal sandbox restrictions.
    continue_session: Resume the most recent agy conversation (stateful).
    conversation_id: Resume a specific agy conversation by ID (stateful).
    timeout: Print-mode timeout, e.g., '10m'. Default is '5m'.

Inputs: prompt (required), dirs, tier, yolo, +4 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between delegate_to_antigravity and start_background_job (both run agy tasks), and between check_job_status and research_status (both poll for status). However, descriptions differentiate them well and the contexts are separate.

    Naming Consistency4/5

    Tools follow a consistent snake_case verb_noun pattern (e.g., check_job_status, collect_digests, propose_design_questions). Minor inconsistencies: auto_git_commit uses a prefix, and some verbs are compound (cross_model_review). Overall, the pattern is clear and predictable.

    Tool Count5/5

    With 13 tools, the server covers a broad domain (git, research, design, code review, background jobs) without being excessive. Each tool earns its place, and the count is appropriate for the advertised capabilities.

    Completeness5/5

    The tool surface covers the full lifecycle of research and design pipelines: question proposal, fanout, status polling, collecting digests, and drafting documents. Additionally, git operations, code indexing, and cross-model review are included. No obvious gaps for the intended use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Wraps Google Antigravity CLI into 11 typed MCP tools, enabling any MCP client to invoke agy for code review, prototyping, execution, and long-running tasks.
      11
      61 PyPI
      25
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Lets MCP clients such as Claude Code, Claude Desktop, Cursor, or Codex hand tasks to the Antigravity CLI (agy) so the work runs on the user's Antigravity plan instead of the client's. Exposes tools for delegated coding tasks and reviews, web search with sources, image/PDF analysis, shell command generation or execution, brainstorming, and model/quota checks.
      7
      MIT