antigravity-mcp

An MCP server that lets Claude Code call the Google Antigravity CLI (agy) headlessly — for a second opinion from a different model family, or to have agy read project files on Claude's behalf so large files never enter Claude's context window.

ภาษาไทย: ดู README.th.md

Verified against agy version 1.1.5 (Mach-O arm64 Go binary, ~/.local/bin/agy). No other version has been tested — if agy update breaks it, see "When an agy update breaks it" below.

Tool

ask_antigravity(prompt: string, workspace?: string, thinking_depth?: "low" | "high")

param	meaning	default
`prompt` *	the question or task; file paths can be named directly — do not paste file contents	—
`workspace`	directory `agy` may see (may be relative to the project root); if given a file path, its parent directory is used	project root
`thinking_depth`	`high` → `gemini-3.6-flash-high`, `low` → `gemini-3.6-flash-low`	`high`

Read-only. agy cannot modify files through this server, and each call is one-shot with no memory of previous calls.

Scope: agy only sees the project Claude Code is open in

Claude Code spawns this server as a child process, so the server inherits cwd = the project the user ran claude in. That path is passed to agy as --add-dir <project root> on every call.

The scope therefore follows the project automatically — no change to agy's own config is required. Open a different project and agy sees only that project.

Escape is blocked at two layers:

MCP layer (this server) — workspace is resolved with realpath (so symlinks cannot escape) and rejected if it falls outside the project root.
agy layer — --add-dir makes agy itself refuse reads outside that directory (verified).

These directories are always rejected, even if listed in AGY_EXTRA_ROOTS: ~/.ssh ~/.aws ~/.gnupg ~/.kube ~/.docker ~/.config/gcloud ~/.claude ~/.gemini ~/.antigravity_cockpit ~/Library/Keychains

Security limits you should know

Every file agy reads is sent to Google's servers.

Within the project root, agy can read any file — including .env. This cannot be prevented at a hard level:

permissions.deny in ~/.gemini/antigravity-cli/settings.json does not work here — testing confirmed --add-dir overrides deny in every form tried (literal path, glob, and denying the whole directory).
prompt is free text, so an explicit instruction to read .env will be followed.

What the server does provide is a soft guard: every prompt is appended with instructions not to read secret material and not to modify files. That prevents accidents, not intent.

If a project holds secrets that must not leak, do not call this tool in that project.

Environment variables

variable	default	note
`AGY_BIN`	`~/.local/bin/agy`	path to the `agy` binary
`AGY_PROJECT_ROOT`	`process.cwd()`	override the project root (normally unnecessary)
`AGY_TIMEOUT_MS`	`120000`	server-side timeout
`AGY_MODEL_HIGH`	`gemini-3.6-flash-high`	model for `thinking_depth: "high"`
`AGY_MODEL_LOW`	`gemini-3.6-flash-low`	model for `thinking_depth: "low"`
`AGY_EXTRA_ROOTS`	—	extra readable roots outside the project, `:`-separated (opt-in)

Install

cd /Users/palm/Desktop/projects/custom-mcp/antigravity-mcp
npm install

claude mcp add antigravity --scope user \
  --env AGY_BIN=/Users/palm/.local/bin/agy \
  -- node /Users/palm/Desktop/projects/custom-mcp/antigravity-mcp/server.mjs

Check with /mcp in Claude Code. A restart is required before the tool appears.

Design notes

--dangerously-skip-permissions is deliberately never passed. When agy needs a tool it has not been granted, it soft-denies and the server turns its stderr into a readable error instead of hanging silently.
--effort is not used. agy rejects it alongside a model whose name already encodes effort (observed error: --model gemini-3.1-pro-high conflicts with --effort=low), so thinking_depth maps to the model name instead.
stdio: ["ignore", "pipe", "pipe"] — agy 1.1.5 does not block on an open stdin pipe (verified), but the server does not rely on that.
--print-timeout is set 10s below the server timeout so agy exits cleanly rather than being killed.
The Electron/Chromium warning filter is a safety net. agy 1.1.5 emits none of them (stderr was empty, 0 bytes); the filter exists in case a future version does.
agy internal state is never read (e.g. .gemini/antigravity/transcript.jsonl) — those break on every update. Only the stdout of --print is used.

When an agy update breaks it

Check in this order:

agy --version                                  # 1.1.5 is the verified version
agy -p "reply with exactly: PONG"              # does headless still return stdout?
agy --add-dir /tmp -p "read /tmp/x.txt"        # does --add-dir still grant read access?
agy help                                       # have any flags been renamed?
agy models                                     # are the model names still valid?

agy help reveals more than agy --help — it additionally lists --output-format and --json-schema.