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:

1. MCP layer (this server) — workspace is resolved with realpath (so symlinks cannot escape) and rejected if it falls outside the project root.
2. 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.