Antigravity MCP Server

MCP (Model Context Protocol) server for Google Antigravity CLI (agy) integration. Lets any MCP client (Claude Code, Claude Desktop, Cursor, etc.) delegate tasks to Antigravity's agentic CLI — with model selection (Gemini, Claude, GPT-OSS), conversation resume, and workspace controls.

For the why behind it, read the project write-up on trishchuk.com. It covers how I use Claude Code or Cursor as the lead engineer and hand bounded work to Antigravity: long tasks delegated to the Gemini 4 Orchestrator in an isolated git worktree, read-only plans and reviews from a different model family, and large-context digests. It also has a table for choosing the right tool, the costs and isolation limits to know before delegating, and where Google's multi-agent tooling is heading.

Requirements

• Node.js >= 18
• Antigravity CLI installed (agy --version works) and authenticated (run agy once interactively and sign in with your Google account)

Installation

npm install -g @trishchuk/antigravity-mcp-server

Or run from source:

pnpm install && pnpm build

MCP client configuration

{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["-y", "@trishchuk/antigravity-mcp-server"],
      "env": {
        "AGY_MCP_CWD": "/path/to/your/project"
      }
    }
  }
}

For Claude Code:

claude mcp add antigravity -- npx -y @trishchuk/antigravity-mcp-server

Tools

Tool	Description
ask-antigravity	Run a prompt through agy in print mode. Supports model + effort, mode, session resume, --add-dir, --sandbox, --dangerously-skip-permissions, dry-run.
plan-antigravity	Generate a structured implementation plan (JSON or markdown) without mutating anything.
review-changes	Collect a git diff (working tree / vs base branch / specific commit) and run a structured code review.
brainstorm	Structured ideation (divergent, convergent, SCAMPER, design-thinking, lateral).
digest-antigravity	Ingest many files/directories and answer a focused question using Antigravity's large model context. Credential files (.env, keys…) are withheld.
batch-antigravity	Run multiple atomic tasks sequentially or in parallel (priority order, stop-on-error, concurrency cap).
bg-antigravity	Detached background tasks: start / status / tail / stop / remove / list. State persists in ~/.agy-mcp/bg/ across server restarts.
delegate-antigravity	Long multi-step tasks: runs detached in its own git worktree, on the Orchestrator model by default; live status, follow-up continue turns, result with the agent report + diff.
list-sessions	List / delete / clear conversation sessions.
list-models	Available models (agy models) grouped by family, with the effort levels each accepts and what it is for.
health	Diagnose CLI installation, authentication, models, and session state.
ping, Help, version, metrics	Utilities.

Background, batch and delegate tools default to --dangerously-skip-permissions because print mode cannot answer interactive permission prompts; pass skipPermissions: false to opt out. An explicit mode turns that default off (the mode is the permission policy), and mode: "plan" with skipPermissions: true is rejected.

Models

The model parameter takes a display label (Gemini 4 Hydrogen (High)), a full ID (gemini-4-hydrogen-high), or a base ID plus effort (model: "gemini-4-hydrogen", effort: "xhigh"). A base label with effort is rejected by the CLI. As of Antigravity CLI v1.5.9 (availability depends on your plan — list-models shows the live list):

Family	Base ID	effort	What it is for
Gemini 4 Hydrogen	gemini-4-hydrogen	low, medium, high, xhigh	Fast everyday coding and maintenance (upgrades, boilerplate, tests, docs). The implementer inside Orchestrator.
Gemini 4 Argon	gemini-4-argon	low, medium, high	Maximum reasoning depth on every step; planner of Orchestrator (Argon).
Gemini 4 Carbon	gemini-4-carbon	low, medium, high	Maximum-depth reasoning (e.g. designing complex systems); planner of Orchestrator (Carbon). Ultra / Enterprise only.
Orchestrator (Argon)	gemini-pro-orchestrator-g1-pro	— (fixed)	Long tasks: the planner plans and reviews, Hydrogen implements, builds and tests, and hands back on repeated failures. One agent, no parallel subagents.
Gemini 3.8 Flash	gemini-3.8-flash	low, medium, high
Claude Opus 5.5	claude-opus-5-5	low, medium, high
Claude Sonnet 5.5	claude-sonnet-5-5	low, medium, high
GPT-OSS 120B	gpt-oss-120b	medium	Scheduled for removal on 2026-11-18.

agy --effort accepts low | medium | high | xhigh | max, but each model supports only the subset above (no current model accepts max); a suffixed ID such as gemini-4-hydrogen-high only accepts its own level. Orchestrator has a fixed thinking level and rejects effort.

Omit model and the server passes no --model flag, so the CLI's own default applies ("model" in ~/.gemini/antigravity-cli/settings.json). The label this server uses in its examples and hints is Gemini 4 Hydrogen (High) — see DEFAULT_MODEL in src/constants.ts.

Delegating long tasks

delegate-antigravity hands a multi-step implementation task to Antigravity and returns immediately:

{
  "task": "Add rate limiting to the /api routes",
  "autoTest": "pnpm test",
  "acceptanceCriteria": ["429 after 100 req/min"]
}

• Creates a git worktree on a fresh agy/<random> branch under ~/.agy-mcp/delegations/ and runs agy detached there (survives the MCP call and server restarts).
• Without model, picks the Orchestrator (Carbon if your plan has it, else Argon); otherwise falls back to Gemini 4 Hydrogen (High).
• Captures --output-format stream-json: action: "status" shows steps, tool calls, the last command and the latest text; action: "continue" with a message sends a follow-up turn into the same conversation and worktree; action: "result" returns the agent's final report, outcome (finished_reason), token usage and the diff against the base commit (cleanup: true removes the worktree and branch).
• Per-turn timeout defaults to 2 hours (timeout: 0 = none). stop signals the whole process group (signal: SIGTERM by default, SIGKILL for a run that ignores it).

Sessions and conversation resume

ask-antigravity supports multi-turn conversations:

{
  "prompt": "Analyze src/auth.ts for security issues",
  "sessionId": "auth-review"
}

{
  "prompt": "Now suggest fixes for the issues you found",
  "sessionId": "auth-review"
}

How it works: in text output agy doesn't print its conversation ID to stdout, so the server passes --log-file to a temp file and parses the ID from it (Created conversation <uuid> / conversationID="<uuid>"). The next call with the same sessionId resumes via agy --conversation <uuid>.

You can also pass a native conversationId directly, or continueLatest: true for agy --continue.

Session storage is in-memory (lost on server restart). Configure with:

• AGY_SESSION_TTL_MS — session TTL (default 24h)
• AGY_MAX_SESSIONS — max stored sessions (default 50)
• AGY_MCP_CWD — default working directory for agy runs. Resolution order: workingDir → AGY_MCP_CWD → the project root of an @path in your prompt (ask, digest, delegate) → the server's launch directory

Safety

• skipPermissions: true maps to --dangerously-skip-permissions — agy auto-approves all tool/command permission requests. Use deliberately.
• sandbox: true maps to --sandbox — terminal restrictions enabled.
• Since CLI 1.5.7 headless runs start in Auto mode where it is available, which edits files without asking. plan-antigravity, review-changes, digest-antigravity and brainstorm therefore pass --settings '{"agentMode":"","permissions":{"allow":[]}}': Default mode, plus your allow-rules suspended for that run (otherwise a pre-approved command such as git checkout still executes). A headless run cannot answer permission prompts, so writes and shell commands are auto-denied; reading files works and the answer still reaches stdout. (--mode plan is not used because it writes the answer into a plan artifact instead.)
• mode maps to --mode accept-edits | auto | plan; Auto is not available on every account.
• A delegation worktree isolates git state, not the filesystem: with skipPermissions (the default for background work) the agent can read and write outside it and run any command.
• digest-antigravity never sends credential-like files (.env*, .npmrc, private keys, *.pem, …) and does not follow symlinks while walking directories.
• Cancelling a tool call from the client stops the agy / git processes it started; background and delegated tasks keep running until you stop them.
• An explicit workingDir / cd that does not exist is an error — the server never falls back to another directory.
• Otherwise agy uses your configured permission rules (/permissions in interactive agy).

Development

pnpm build          # tsc
pnpm lint           # tsc --noEmit
pnpm test           # build + node --test
pnpm format         # prettier

License

MIT