antigravity-cli-mcp-slim

A thin, auditable MCP server wrapping the Antigravity CLI (agy).

Why

When you add an MCP server to your AI coding tool, every prompt and code snippet you send flows through that wrapper. Most CLI-wrapping MCP servers are small, individually maintained packages — and recent supply-chain incidents (xz-utils, postmark-mcp, the npm chalk/debug compromise) show that "small and useful" is not the same as "safe to trust blindly."

This project takes the opposite stance: instead of asking you to trust it, it tries to be easy to audit.

• Single file — the whole server is src/antigravity_cli_mcp_slim/server.py, readable end-to-end in one sitting
• One third-party dependency (mcp) — minimal supply-chain surface
• Faithful CLI mapping — every typed parameter mirrors a real agy flag by name, so it is obvious which flags an invocation actually sets
• Forward-compatible — any new or uncommon agy flag is reachable via extra_args without touching this server
• Configurable binary path — $AGY_CMD lets you swap or wrap the agy binary
• Transparent — every invocation logs the exact argv to stderr

Read server.py before you install. That is the point.

Prerequisites

• The agy CLI, version 1.1.8 or newer, installed and on $PATH (or pointed to via $AGY_CMD). See the official Antigravity CLI repository and install docs. This server always passes --output-format json, and 1.1.8 is the first release to document and support that flag.
• agy already authenticated — this wrapper does not manage login; it surfaces agy's own error output if the CLI is not ready.

Installation

# Run directly without installing
uvx antigravity-cli-mcp-slim

# Install from PyPI
pip install antigravity-cli-mcp-slim

# Run from GitHub HEAD
uvx --from git+https://github.com/tksfjt1024/antigravity-cli-mcp-slim antigravity-cli-mcp-slim

Usage as an MCP server

Claude Code

claude mcp add antigravity-cli uvx antigravity-cli-mcp-slim

Or manually in ~/.claude.json:

{
  "mcpServers": {
    "antigravity-cli": {
      "type": "stdio",
      "command": "uvx",
      "args": ["antigravity-cli-mcp-slim"]
    }
  }
}

If agy is not on the launching process's $PATH, point $AGY_CMD at it:

{
  "mcpServers": {
    "antigravity-cli": {
      "type": "stdio",
      "command": "uvx",
      "args": ["antigravity-cli-mcp-slim"],
      "env": { "AGY_CMD": "/absolute/path/to/agy" }
    }
  }
}

Other MCP clients

Any MCP-compatible client can launch the server via stdio:

uvx antigravity-cli-mcp-slim

Tool: consult_agy

Runs a single agy invocation in non-interactive print mode (agy --print). agy is an agentic assistant: it autonomously reads files in directory (and any add_dir) to fulfill the request, then prints the response.

The tool returns agy's response text followed by one metadata line:

[agy] status=SUCCESS conversation_id=133cb55a-5128-463a-835c-b8362519876f total_tokens=18035

status is whatever agy reported for the run and is always present; the other fields appear only when the run produced them. The values shown here are examples, not the full set agy can return. A run agy itself calls failed also carries its reason in error, and the tool result is flagged isError instead of coming back as a successful call:

[agy] status=ERROR error=timeout waiting for response conversation_id=a35d1505-804e-4159-9c76-ea2ff821c290

Starting in agy 1.4.11, a turn that stops early (a print_timeout hit, an error, or an interruption) exits 0 and records the cause in finished_reason. Such a run is also flagged isError, even when agy returns a partial answer: the output starts with [ERROR] agy did not finish the turn (finished_reason=…), followed by the metadata line and, if present, the partial answer under partial response:.

[agy] status=SUCCESS finished_reason=print_timeout conversation_id=38132840-0311-4450-bc1f-ec153a925b98

Pass that conversation_id back as conversation to resume the same run. Prefer it over continue, which races with any other invocation for whichever conversation happens to be the most recent one.

Security note: dangerously_skip_permissions

dangerously_skip_permissions: true passes --dangerously-skip-permissions, which auto-approves all of agy's tool permission requests — including running shell commands and editing files — with no prompt. The parameter keeps the dangerously_ prefix on purpose: enable it only in a trusted, isolated workspace where you fully trust the prompt. It defaults to false.

Cross-repository analysis example

Analyze multiple repositories from a single invocation by adding directories to the workspace:

{
  "name": "consult_agy",
  "arguments": {
    "query": "Compare the API surface of the main service with the clients that call it",
    "directory": "/path/to/main-service",
    "add_dir": [
      "/path/to/client-a",
      "/path/to/client-b"
    ]
  }
}

This launches agy --print "..." --output-format json --add-dir /path/to/client-a --add-dir /path/to/client-b, giving the agent read access to all three workspaces in one session.

Conversation continuity

agy can resume prior conversations. This wrapper exposes that directly and stays stateless itself:

• continue: true resumes the most recent conversation. Because "most recent" is shared state, concurrent calls can race on it — prefer conversation when it matters.
• conversation: "<ID>" resumes a specific conversation by id.

The two are mutually exclusive; passing both returns an error.

Timeout configuration

There are two independent timeouts:

• print_timeout — agy's own wait timeout (Go duration; agy defaults to about 5 minutes).
• timeout_seconds — this wrapper's hard wall-clock limit (default 660).

Keep timeout_seconds longer than print_timeout so agy can finish or time out cleanly before the wrapper force-kills the subprocess. When you raise print_timeout for a long task, raise timeout_seconds to match.

On timeout, the wrapper kills the subprocess's whole process group and then waits up to 20 additional seconds to collect any buffered output and reap the process, so the effective wall-clock ceiling is timeout_seconds + 20.

Forward-compatibility example

If a future agy release adds a new flag (say --super-mode), use it immediately without updating this server:

{
  "name": "consult_agy",
  "arguments": {
    "query": "...",
    "directory": "...",
    "extra_args": ["--super-mode"]
  }
}

Configuration

Development

# Install dev dependencies
pip install -e ".[test,dev]"

# Lint
ruff check .

# Test
pytest

License

MIT © tksfjt1024