agy-mcp

Personal tool, published as-is. This is not a product: it is not on npm, it is not maintained for anyone else, and there is no support. The repository is archived — read it, copy from it, fork it freely, but do not expect issues or pull requests to be answered. If you want something maintained, agy-bridge is an actively developed alternative with a broader tool surface.

An MCP stdio server that makes the Antigravity CLI (agy) a first-class tool inside Claude Code — and verifies, on every single call, which backend model actually answered.

If you pay for both Claude Code and Google AI Pro, this lets you spend the cheaper subscription on the cheaper work without leaving Claude Code. Claude stays the driver; agy becomes a tool it can hand a task to.

You  →  Claude Code  →  agy_ask(tier: "trivial")  →  agy  →  Gemini Flash
                                                       ↓
                                   [verification] OK — served by "Gemini 3.7 Flash (Low)"

Why not an LLM gateway or proxy

The common way to mix providers is to point Claude Code's Anthropic API traffic at a proxy that translates it to another vendor's API. That means intercepting requests, and often reusing credentials issued to a different client.

This server does none of that. There is no proxy, no API translation, no credential relay, and nothing is re-signed or intercepted. Claude Code talks to Anthropic on your Anthropic account. agy talks to Google on your Google account, through Google's own official CLI, exactly as if you had typed the command yourself. All this server does is let Claude spawn that CLI as a subprocess and read its output.

Check your own subscriptions' terms and decide for yourself whether this fits them. This README makes no legal claim on your behalf.

What you get over calling agy through Bash

• Backend verification on every call. agy's --model flag is not always honoured, and the model's own self-report will not tell you. Every result is prefixed with a [verification] line naming the model that really served it, parsed out of agy's own log.
• Known-broken model ids are refused by default, rather than silently answering from the wrong model.
• New routing bugs are detected on their own — see Model routing verification.
• Difficulty tiers, not model ids. Claude picks trivial / standard / hard / reasoning, and the server resolves that against the live model list.
• No shell permission prompt per call, and no risk of the command being reshaped by a shell wrapper.
• Long runs do not die on the tool timeout. A deep research call hands back a job_id; the run continues in the background and Claude collects it with agy_result.
• The dangerous capability is a separate tool (agy_exec), so the rest can be allowlisted safely. See Security model.

Requirements

• Node.js ≥ 18 (zero dependencies)
• The Google Antigravity CLI (agy) installed, on PATH, and signed in
• Claude Code

Built and tested against agy 1.1.13, and against every release since 1.1.7.

Install

Not published to npm, and there are no plans to. Clone it and point Claude Code at the script — there is nothing to build, and no dependencies to install.

git clone https://github.com/Sh3rm/agy-mcp.git
cd agy-mcp
npm test          # optional; needs neither agy nor network

Register with Claude Code

MCP servers can be registered at three scopes. Pick the one that matches how you want to use it. Use the absolute path to bin/agy-mcp from your clone.

User scope — available in every project on this machine. Most people want this.

claude mcp add agy --scope user -- /absolute/path/to/agy-mcp/bin/agy-mcp

Project scope — checked into the repo, shared with your team. Creates or updates .mcp.json in the project root.

claude mcp add agy --scope project -- /absolute/path/to/agy-mcp/bin/agy-mcp

The resulting .mcp.json:

{
  "mcpServers": {
    "agy": {
      "type": "stdio",
      "command": "/absolute/path/to/agy-mcp/bin/agy-mcp",
      "args": [],
      "env": {}
    }
  }
}

Local scope — this project only, not shared.

claude mcp add agy --scope local -- /absolute/path/to/agy-mcp/bin/agy-mcp

Then verify:

claude mcp list

Restart Claude Code after registering, and the seven agy_* tools appear.

Tools

Tool	Purpose	Key parameters
agy_ask	General delegation: research, summarising, codegen, conversions. Cannot grant shell or file access.	prompt, tier, model, parallel_subagents, effort, conversation_id, continue_conversation, wait_seconds
agy_research	Web research with Google Search grounding and parallel subagents. Also exec-free.	question, plus the common parameters above
agy_exec	Local shell and file access on this machine. Prompts every time by design.	everything in agy_ask, plus workdirs, sandbox
agy_result	Collect a long run that handed back a job_id.	job_id, wait_seconds
agy_models	Live model list, current tier map, blocked ids, observed misroutings.	—
agy_usage	Remaining quota per limit bucket. Free: no agent turn, no tokens, no conversation. Needs agy >= 1.1.11.	—
agy_selftest	Call every model once and report which backend really served it. Run this after agy update.	—

Difficulty tiers

Tiers resolve against the live model list from agy models, by pattern — highest version wins, broken ids are skipped. A new Gemini generation is adopted with no code change.

Tier	Resolves to	Use for
trivial	Gemini Flash, low effort	single-fact lookups, formatting
standard	Gemini Flash, medium effort	everyday tasks, straightforward search
hard	Gemini Flash, high effort	multi-step work needing a capable model
reasoning	Gemini Pro	genuinely hard synthesis
claude	Claude Sonnet	when the Gemini tiers are not enough
claude_max	Claude Opus	quota-constrained, use sparingly

Model routing verification

agy has had model ids that silently routed to a different backend — the flag is accepted, the response looks normal, and the model's own claim about its identity is not reliable. From 1.1.7 through 1.1.10:

gemini-3.1-pro-high   →  actually served by "Gemini 3.6 Flash (High)"
gemini-3.5-flash-low  →  actually served by "Gemini 3.5 Flash (Medium)"

Both were fixed in agy 1.1.11, so nothing is blocked by default today. The cause turned out to be effort variants with no backend behind them, advertised by agy models regardless; 1.1.11 returns real labels for both.

That history is the argument for the check, not against it. The bug class survived four releases, and neither release note was a reliable signal: 1.1.10 shipped a --model/--effort fix that read exactly like this bug and did not fix it, while 1.1.11 fixed it without mentioning routing at all. So the verification runs on every call regardless of what is currently known to be broken.

This server runs every call with --log-file and parses agy's own line:

Propagating selected model override to backend: label="..."

The requested id and the reported label are compared by normalisation, not against a lookup table:

normalize(s) = s.toLowerCase().replace(/[^a-z0-9]/g, '')
match if normalize(label).startsWith(normalize(requestedId))

Because there is no hardcoded table, a routing bug introduced in a future agy build is caught the same way the known ones are. When a mismatch is detected the server names the model that actually answered, records it in ~/.local/state/agy-mcp/mismatches.json, and surfaces it in agy_models.

Ids known to be broken are refused before the call; force_broken_model overrides that and returns an explicit warning instead of silent wrong-model output. The seeded list is empty as of agy 1.1.11. To block an id yourself without editing the source, set AGY_MCP_BLOCK="id1,id2" in the server's environment.

Security model

The reason there is a separate agy_exec tool is that MCP permission rules in Claude Code match on tool name only — there is no argument-level matching. If local execution were a boolean parameter on agy_ask, allowlisting agy_ask would allowlist arbitrary shell access.

So the capability is split:

• agy_ask and agy_research can never give agy shell or file access, whatever arguments are passed. Safe to allowlist.
• agy_exec is the only path to --dangerously-skip-permissions. Do not allowlist it. Let it prompt every time.

A suggested allowlist for ~/.claude/settings.json, deliberately excluding agy_exec:

{
  "permissions": {
    "allow": [
      "mcp__agy__agy_ask",
      "mcp__agy__agy_research",
      "mcp__agy__agy_result",
      "mcp__agy__agy_models",
      "mcp__agy__agy_selftest"
    ]
  }
}

What agy_exec does and does not enforce

workdirs is required and validated before agy is started. Every entry must be an absolute path to an existing directory; symlinks are resolved first, and the filesystem root, the home directory and system roots are refused outright — those are the over-scopes people reach for by accident. The first entry also becomes the working directory of the agy process, so relative paths resolve inside the scope. sandbox defaults to true, enabling agy's own terminal restrictions; the safer setting is what you get by not thinking about it.

Be blunt about the limit of all this: it constrains the invocation, not the agent. agy still runs with --dangerously-skip-permissions and has a shell. Writing "read-only" into the prompt is an instruction to the model, not an enforced sandbox — a request that will probably be respected, never a guarantee. This project does not claim to jail agy, and you should not describe it that way to your users.

Configuration

Variable	Default	Meaning
AGY_BIN	agy	Path to the agy binary

State (detected misroutings, background jobs) lives in ~/.local/state/agy-mcp/.

Known limitations

• The seeded broken-model list is tied to an agy version. It may be stale in either direction — it has been both. Run agy_selftest after agy update to re-map.
• agy models has changed its output format before, from bare ids to id<TAB>Label in 1.1.11. The parser accepts both, but a third shape would fail silently by falling back to the seed list. agy_models says which list it is showing; check it after an agy update. (1.1.12's release notes announced an --output-format json flag for the models subcommand, which would have made this robust — it does not exist in 1.1.13, so the text parser stays.)
• agy may decline remote-host work framed as a security audit. Describing the task accurately — your own machine, access already configured, a configuration inventory rather than a security analysis — is usually what was missing.
• The agy usage subcommand still needs a real TTY. The /usage slash command in print mode does not, as of 1.1.11, which is what agy_usage uses.
• Headless agy cannot prompt for permission, which is exactly why file and shell work needs agy_exec.
• Parallel subagents in --print mode are real — each has a conversation tree under ~/.gemini/antigravity-cli/brain/<id>/ with genuine search grounding. The mechanism is trustworthy; individual figures can still be stale, so spot-check anything load-bearing.

Disclaimer

Unofficial and unaffiliated. Not endorsed by Google or Anthropic. "Antigravity", "Gemini", "Claude" and "Claude Code" belong to their respective owners; they are used here only to describe what this tool interoperates with.

License

MIT