Antigravity MCP Server

An MCP server connecting Claude Code, Cursor, and other AI assistants to Google Antigravity CLI · npm package @trishchuk/antigravity-mcp-server · sibling of Codex MCP Server →

I built this server so Claude Code or Cursor can hand work to Google's Antigravity CLI (agy) without leaving the primary session. It runs agy headless and exposes a few distinct workflows as MCP tools: read-only plans and code reviews, large-context codebase digests, batch and background jobs, and multi-step tasks delegated to an isolated git worktree.

Why Hand Work to Antigravity

Running everything through one coding assistant hits two limits fast: its context fills up with broad exploration, and the blind spots of a single model family survive its own self-review. I use Claude Code or Cursor as the lead engineer: it holds the conversation and the architectural context, defines the task and decides what to accept. Bounded work goes to agy.

In practice, three workflows justify the extra tool call:

• Delegate bounded, testable implementation work. Give delegate-antigravity a task, acceptanceCriteria and an autoTest command. It creates a new branch in a separate git worktree and runs the Orchestrator model when your plan includes it: a Gemini 4 planner scopes the change, Gemini 4 Hydrogen edits and runs verification, and control returns to the planner when verification stalls. Your lead agent stays responsive, polls status, steers with continue, and reviews the final diff before anything touches your checkout. Skip it for quick single-file edits: the worktree setup and model handoffs only pay off on multi-step work.
• Use a different model family for plans and reviews. A critique from another vendor catches assumptions your primary model shares with itself. plan-antigravity and review-changes run locked down: the agent can read files, while writes and shell commands are denied, so they are safe to run on a dirty working tree before you commit to an approach.
• Ask one focused question across many files. digest-antigravity packs dozens of files into one prompt and answers a targeted question without filling your lead agent's working context. Because file contents leave your machine, known credential files (.env*, .npmrc, private keys) are withheld and symlinks are not followed.

Choosing a Tool

Capabilities at a Glance

• Long-Task Delegation — isolated git worktree, fresh branch, Orchestrator by default, follow-up turns, diff on completion
• Live Progress — structured stream-json output, so status shows steps, tool calls and the agent's latest text
• Read-Only Analysis — plans, reviews, digests and brainstorms can read files but cannot write or run shell commands
• Native Resume — multi-turn sessions mapped to Antigravity's own conversation IDs
• Model & Effort Control — any agy models ID or label, plus per-model effort (low … xhigh)
• Large-Context Digest — feed many files into one prompt and ask a focused question; known credential files are withheld
• Cancellation — cancelling a tool call in the client stops the agy process it started
• Batch & Background — parallel atomic tasks with a concurrency cap; detached jobs persisted on disk
• Model Discovery — list-models groups models by family, with accepted effort levels and intended use
• Health Diagnostics — CLI install, authentication, models and session state

Quick Start

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

Prerequisites: Node.js 18+, Antigravity CLI installed (agy --version) and signed in (run agy once interactively).

Manual MCP Configuration

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

Where it goes: claude mcp add above configures Claude Code directly. Clients that read a config file take the same mcpServers block: Cursor in ~/.cursor/mcp.json (or .cursor/mcp.json in a project), Claude Desktop in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

Usage Examples

// Delegate a long task (Orchestrator, isolated worktree)
'delegate to antigravity: migrate the payments module to the new SDK,
 acceptanceCriteria: ["no public API changes"], autoTest: "pnpm test"'
'check status of the antigravity delegation'
'tell the delegation: the webhook tests still fail, fix the signature check'
'get the delegation result and show me the diff'

// Second opinion from another vendor
'review my uncommitted changes with antigravity'
'plan-antigravity goal:"add rate limiting to the public API" format:"markdown"'

// Large-context question
'digest-antigravity question:"where is auth state mutated?" paths:["src/", "lib/"]'

// Specific model and effort
'ask antigravity model:"gemini-4-hydrogen" effort:"xhigh" prompt:"explain src/scheduler.ts"'

// Multi-turn conversation
'ask antigravity sessionId:"auth" prompt:"analyze @src/auth.ts for security issues"'
'ask antigravity sessionId:"auth" prompt:"now suggest fixes"'

Tools

Models

By default the model parameter is omitted and the CLI uses its own default ("model" in ~/.gemini/antigravity-cli/settings.json). The exception is delegate-antigravity: it picks Orchestrator (Carbon), then Orchestrator (Argon), whichever your account has, and falls back to Gemini 4 Hydrogen (High). model accepts either column of agy models, the ID or the display label. You can also pass a base ID such as gemini-4-hydrogen together with effort.

Your plan decides what you can run. Per Google, Orchestrator (Argon) needs a paid Google AI Pro or Ultra plan, Orchestrator (Carbon) needs Ultra, and Gemini 4 Carbon needs Ultra or Enterprise. Run list-models first to see what your account exposes and which effort levels each family accepts. Orchestrator uses a fixed thinking level, so passing effort to it fails validation. Antigravity also serves claude-opus-5-5 and claude-sonnet-5-5, but if your lead agent is already Claude, a Gemini model is what gives you a genuinely independent second opinion.

How It Works

Delegation Lifecycle

start creates a worktree under ~/.agy-mcp/delegations/ on a new branch agy/<random> and launches a detached agy run. The run is told to plan, implement, verify after every step (looping on autoTest if you give one) and finish with a report. It is told not to commit.

{ "action": "start", "task": "Add CSV export to the reports page",
  "acceptanceCriteria": ["streams large files", "covered by tests"], "autoTest": "pnpm test" }
{ "action": "status", "taskId": "…" }
{ "action": "continue", "taskId": "…", "message": "Keep the existing column order" }
{ "action": "result", "taskId": "…", "cleanup": true }

result returns the agent's final report, the run's outcome, its token usage, a diffstat, untracked files and the full diff against the base commit. Delegations run detached, so they survive the MCP call and server restarts. Calls on the same delegation are serialized, so two follow-ups never start two runs in one worktree. Each turn defaults to a 2-hour limit, which bounds a stalled verification loop but can still cost real time and quota.

Applying the result. The agent's work lives on its agy/<random> branch. Merge or cherry-pick that branch, or apply the returned diff, and only then call result with cleanup: true: cleanup removes the worktree and deletes the branch.

Sessions & Resume

The server tracks sessions per repository and maps each internal sessionId to Antigravity's native conversation ID, recovered from the CLI's own log file or from the stream-json events, and resumes with --conversation. Concurrent calls that share a session are serialized, and a sessionId reused in another repository starts a fresh conversation instead of continuing the old one.

{ "prompt": "analyze code", "sessionId": "my-session" }
{ "prompt": "continue from here", "sessionId": "my-session" }
{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }

Environment:

• AGY_MCP_CWD — default working directory for agy runs. Resolution order: workingDir → AGY_MCP_CWD → the project root of an @path in your prompt → the server's launch directory. A workingDir that does not exist is an error, never a silent fallback.
• AGY_SESSION_TTL_MS — session TTL (default: 24h)
• AGY_MAX_SESSIONS — max sessions (default: 50)

Read-Only Tools

Since CLI 1.5.7, headless runs start in Auto mode where it is available, and Auto mode edits files without asking. plan-antigravity, review-changes, digest-antigravity and brainstorm override this with a session-only --settings overlay that selects the Default agent mode and empties permissions.allow for that run, because a pre-approved command such as git checkout would otherwise still execute. A headless run in Default mode cannot answer a permission prompt, so writes and shell commands are denied while reading files still works and the answer comes back on stdout. These tools also refuse --dangerously-skip-permissions, and review diffs are treated as untrusted input.

Advanced Options

CLI Compatibility

Validated against Antigravity CLI 1.5.9. Notable current behavior:

• Headless runs default to Auto mode since 1.5.7 (per agy changelog). Read-only tools pin Default mode explicitly.
• --effort levels vary by model, and Orchestrator rejects the flag. list-models shows what each family accepts.
• --output-format stream-json drives delegation progress. The final result event carries conversation_id, status, response and usage.
• Auto mode needs the terminal sandbox and is not offered on every account; without it, delegated work needs skipPermissions.
• GPT-OSS 120B, Claude Sonnet 4.6 and Claude Opus 4.6 are scheduled for removal from Antigravity on 2026-11-18.

Where This Is Heading

Building against agy made one shift hard to miss: coding agents are moving from one general-purpose model toward specialized roles and machine-readable control.

Planner and implementer are becoming separate models. Orchestrator puts that split into the model picker: Argon or Carbon runs a read-only planning phase, Hydrogen edits and verifies, and control escalates back to the planner when verification stalls (for example, a step failing twice). Google reports near-Carbon success rates on Terminal-Bench 4.1 with 24% less quota and 19% faster runs. Whether those ratios hold on your repository or not, the pattern nests cleanly with MCP: Claude Code plans and reviews at the top, and Orchestrator runs its own plan-and-execute loop underneath.

Single agents are becoming coordinators. /swarm (in preview) starts parallel workers in isolated git worktrees, with verifiers that run the tests and challenge the diffs over a shared append-only message board. CLI 1.5.9 added run_workflow, which fans work out to subagents from a Python script. This server does not wrap either yet; for bounded parallelism today, use batch-antigravity.

Headless output is now something other programs can read. JSON and stream-json output, with conversation IDs, status and token usage, turned delegation from "spawn a process and grep stdout" into a process you can observe and resume. --json-schema enforces a schema on the final answer. The server does not use it yet; schema-constrained plans and reviews are the practical next step when another agent consumes the result.

The integration surface is broader than MCP. agy acp serves the agent over the Agent Client Protocol to editors such as Zed and JetBrains IDEs. agy mcp lets it use MCP servers, and this server exposes it as MCP tools. --remote-agent already runs conversations on remote agents, so delegated work may soon leave the laptop.

The cost and isolation trade-off. Even with sandbox on, a headless run with skipPermissions is not an OS container: sandbox restricts terminal commands, but the agent can still reach outside the worktree. Orchestrator spends fewer tokens than running the planner model for every step, yet Google notes that parallel multi-agent runs use quota much faster than a normal chat, and Orchestrator (Carbon) is Ultra-only. I treat multi-agent delegation as a deliberate budget decision, not a default for every prompt.

Troubleshooting

agy --version    # Check CLI version
agy              # Sign in interactively once
agy models       # Confirm auth and see available models

Use the health tool to check the CLI install, authentication, models and sessions: 'use health verbose:true'. Common gotchas:

• A workingDir that does not exist fails fast instead of falling back to another directory.
• Orchestrator rejects any effort value; pass a base model ID such as gemini-4-hydrogen when you want to set effort.
• Auto mode needs the terminal sandbox and is missing on some accounts; without it, delegated runs rely on skipPermissions.
• A delegation does not see uncommitted changes: it branches from the base commit.

Further Reading

• @trishchuk/antigravity-mcp-server on npm
• Source on GitHub
• Antigravity CLI docs
• Antigravity models
• Gemini 4 Hydrogen and Orchestrator
• Model Context Protocol
• Siblings: Codex MCP Server · kimi-mcp-server