Antigravity MCP Server

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

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):

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          # tscpnpm lint           # tsc --noEmitpnpm test           # build + node --testpnpm format         # prettier

License

MIT