Antigravity Worker MCP

Product requirements | Protocol | Clients | Audit logging | Verification

A Rust MCP worker for the official Google Antigravity CLI. Codex, Claude Code, and other stdio MCP clients can submit background tasks, check status, read native answers, and cancel execution. Run the standalone executable or use the optional npm launcher.

Default: no isolation, full current-user permissions, automatic execution, no task deadline. Tasks run in the original configured workspace with --dangerously-skip-permissions. Set isolation: true for a separate working copy, or select execution_mode: "analysis" for read-only inputs.

Headless mode by itself does not approve every tool action. The wrapper passes the explicit automatic-approval flag to the official agy; no agy-yolo alias or separate executable is required.

Full local audit logging is also enabled by default. It retains MCP requests/responses, selected inputs, CLI streams and terminal results after shutdown. Logs rotate without automatic deletion. Use --no-audit or auditLogging: false to disable wrapper logging completely. See audit logging for storage, privacy and failure behavior.

Version 0.3 is experimental. It uses your installed agy and cached login on Linux, macOS or Windows. This community project has no Google affiliation and does not implement Google's private model APIs or change account overage settings.

Why this exists

I built this because the Google Antigravity CLI in my Google One Ultra 20X subscription is awkward to use. The model allowance is generous; my patience with the CLI is less so. This wrapper lets Codex or Claude Code handle task submission, progress and answers through MCP, while the official CLI does the model work.

Related MCP server: sub-antigravity

Install

Download the archive matching your operating system and architecture from GitHub Releases, verify its SHA-256 against SHA256SUMS, and extract it. Archives contain the executable, licenses, notices and English documentation. The official CLI is installed separately.

CI runs native compilation, lint, tests and packaging for all six targets. Linux/macOS archives use .tar.gz; Windows archives use .zip and contain antigravity-worker-mcp.exe. Tag releases publish all six archives, the npm launcher and checksums. See the verification record for actual tested environments and remaining gaps.

Run with npx

The release includes an npm package that works without an npm registry publication. With Node.js 20.11 or newer and npm installed:

npx -y --package=https://github.com/getio0909/antigravity-worker-mcp/releases/download/v0.3.0/antigravity-worker-mcp-0.3.0.tgz antigravity-worker-mcp --version
npx -y --package=https://github.com/getio0909/antigravity-worker-mcp/releases/download/v0.3.0/antigravity-worker-mcp-0.3.0.tgz antigravity-worker-mcp --config /absolute/path/config.local.json

The dependency-free Node launcher downloads the matching Rust archive, verifies its release SHA-256, and caches the extracted executable and documentation. Later launches verify the cached executable before using it. Arguments, working directory, environment and stdin/stdout pass through to Rust; download messages use stderr. The official agy still needs a separate installation and login. Unix extraction requires tar; Windows uses PowerShell. Linux musl systems and older glibc need a source build.

Cache locations are $XDG_CACHE_HOME/antigravity-worker-mcp or ~/.cache/antigravity-worker-mcp on Linux, ~/Library/Caches/antigravity-worker-mcp on macOS, and %LOCALAPPDATA%\antigravity-worker-mcp\Cache on Windows. A cache verification error names the version/target directory to remove before retrying. Direct binary execution needs no Node.js runtime.

The unqualified command npx -y antigravity-worker-mcp becomes available after a separate npm registry publication. This release uses the explicit GitHub package URL above; it does not claim registry availability.

Build from source

Alternatively, use an existing Rust toolchain 1.89 or newer:

git clone https://github.com/getio0909/antigravity-worker-mcp.git
cd antigravity-worker-mcp
cargo build --locked --release --bin antigravity-worker-mcp
./target/release/antigravity-worker-mcp --version
cp examples/config.example.json config.local.json

Install the official CLI through Google's installation documentation and authenticate once with interactive agy. List your available model slugs:

agy models

Edit config.local.json: set absolute executable and project paths, then replace the model placeholders with valid slugs. Local configurations are ignored by Git. Default host mode needs the official CLI; optional isolation also needs Bubblewrap, working unprivileged user namespaces, and Git for patches.

On Windows, use the Windows configuration example, the actual installed agy.exe path and absolute Windows paths. JSON backslashes must be escaped. Client registration accepts the .exe path in place of the Unix executable path shown below.

antigravity-worker-mcp --config /absolute/path/config.local.json

The server speaks MCP on stdin/stdout. A terminal without a client waits for input. Configuration errors go to stderr as sanitized JSON.

Add to Codex or Claude Code

codex mcp add antigravity-worker -- /absolute/path/antigravity-worker-mcp --config /absolute/path/config.local.json
claude mcp add --scope user antigravity-worker -- /absolute/path/antigravity-worker-mcp --config /absolute/path/config.local.json

Or register the npm launcher on Linux/macOS:

codex mcp add antigravity-worker -- npx -y --package=https://github.com/getio0909/antigravity-worker-mcp/releases/download/v0.3.0/antigravity-worker-mcp-0.3.0.tgz antigravity-worker-mcp --config /absolute/path/config.local.json
claude mcp add --scope user antigravity-worker -- npx -y --package=https://github.com/getio0909/antigravity-worker-mcp/releases/download/v0.3.0/antigravity-worker-mcp-0.3.0.tgz antigravity-worker-mcp --config /absolute/path/config.local.json

On Windows, register cmd /c npx in place of npx so the MCP host can launch npm's command shim. Run the --version command once before registration to populate the native executable cache.

Restart an existing session to load the server. Codex /mcp shows connection status; claude mcp list checks Claude Code's configured connection. See the Codex documentation and Claude Code documentation for host-specific settings.

The client guide covers CC Switch setup, startup timeouts, temporary headless connections, approvals and working directories. Codex's default ten-second startup timeout can be too short for an initial npx download; prewarm the cache or increase it.

To remove registrations:

codex mcp remove antigravity-worker
claude mcp remove --scope user antigravity-worker

The verification record distinguishes tested MCP protocol behavior from actual host-client sessions. Installing this repository does not modify either client's global configuration automatically.

Simple invocation

Only instructions is required. The task text is sent unchanged, and the native answer can be text, Markdown, code or JSON. No report format or evidence schema is imposed. root defaults to the submitting connection's working directory; set it explicitly when the project location matters. model optionally selects a native slug; kind is an optional label with no effect on execution.

Tools

Default automatic execution:

{
  "instructions": "Inspect this project and explain how it works.",
  "root": "/absolute/path/to/project"
}

Optional working copy:

{
  "root": "/absolute/path/to/project",
  "files": ["src/example.rs", "Cargo.toml"],
  "instructions": "Implement the scoped change and report the checks performed.",
  "isolation": true
}

timeout_seconds: 0 disables the deadline. Omit it to use timeoutSeconds, which defaults to zero. A positive value enables an optional deadline including queue time, with no 900-second cap. A client tool-call timeout covers each control request, not the background task. Supply the same idempotency_key when retrying an uncertain submission; a different task with that key is rejected.

Follow next_offset in ag_result; use section: "patch" for the working-copy patch. Review the complete patch before applying it. All results carry verification_status: "unverified"; the host agent evaluates the answer and checks any claimed effects.

Isolated mode copies only selected UTF-8 files, up to 100 files, 256 KiB each and 4 MiB total. It does not copy the complete repository, .git, local settings, secrets or installed dependencies. Include materials needed for checks and use runtimePaths to mount additional toolchain directories read-only. Host mode can use the original full project.

Execution and data

Workspace and analysis modes require Linux. macOS and Windows reject isolation requests with ISOLATION_UNSUPPORTED; they do not silently run them on the host.

allowHostExecution defaults to true. Set it to false to reject host tasks. The starting-directory allowlist is disabled when allowedRoots is absent or empty. An explicitly configured list validates only the initial directory. Client-side tool approval remains controlled by the MCP host.

Isolated execution keeps the original project outside the mount namespace, but exposes system programs, configured runtimes, network access and the CLI's read-only authentication file. It is not a network firewall or an exfiltration barrier against hostile tasks. Host cancellation covers the supervised CLI and process group; detached services and external side effects can remain. A runner crash or reboot is reported as interrupted work, without automatic replay.

Windows first attempts direct Job Object breakaway. If the client prevents it, windowsDesktopFallback can launch through a temporary current-user Task Scheduler registration using the existing desktop sign-in. This parameter defaults to true. It saves no password or request file, transfers startup input through a private local pipe and removes temporary registration after startup. Disable it to require direct launch. Without a usable route, the job returns BACKGROUND_UNAVAILABLE. The desktop route requires an interactive sign-in and uses profile environment settings rather than transient MCP-process overrides; see the client guide.

Jobs run in detached supervisor processes and survive the submitting client disconnecting. Clients using the same private stateDirectory can query or cancel the same job. Native answers and patches are stored locally and do not expire by default. retentionSeconds can enable expiry; ag_forget frees a terminal result slot without removing audit logs or its idempotency record. maxJobs bounds retained results, so a full store rejects new submissions instead of silently deleting answers. Full audit logs persist independently in the private state directory; they include task instructions and observed tool output. Isolated CLI history is temporary. Default host mode uses the official CLI's normal history and retention settings. Disabling wrapper logs does not change client, CLI or provider retention.

The underlying CLI is an autonomous agent. The wrapper passes task instructions unchanged and returns the original answer. It adds no report schema, task categories or host-tool allowlist. The agent chooses its commands, reads and working steps. Audit logs record those actions; they do not veto them. Results remain unverified; inspect actual results and side effects.

Instances sharing one stateDirectory share one execution lock and serialize CLI jobs. The queue, results and quota pause are shared. Scheduling follows submission order. Different directories or machines have independent locks. Quota/capacity failures hold queued jobs until explicit ag_resume; failed jobs are never replayed. Token usage is reported when available; remaining subscription quota is unknown.

Development

cargo fmt --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-features
cargo build --locked --release --bin antigravity-worker-mcp
npm test

Tests use a native CLI fixture and real processes, Bubblewrap, advisory locks and stdio MCP. They do not require Google authentication or invoke a model. See architecture, contributing, security, and the complete RPD.

The project uses the MIT license. Dependencies retain their own licenses. Google Antigravity and its models remain subject to their service terms. GitHub hosts source, binary releases and the npm launcher tarball; npm registry, crates.io and MCP Registry publication are separate roadmap items.