# 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](./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

```bash
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:

```bash
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`.