Skip to main content
Glama
Sign In
antigravity

antigravity

by BerryUIKI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

AGY MCP for Codex

A small, dependency-free MCP server that lets OpenAI Codex delegate local tasks to Google Antigravity CLI (agy). It starts Antigravity in headless mode, returns immediately with a task ID, and lets Codex poll for the final response.

This is an independent community bridge. It is not an official Google or OpenAI project.

What it provides

MCP tool

Purpose

antigravity_status

Find the local CLI and list tasks held by the current MCP process

antigravity_start

Start an Antigravity task and return a task_id

antigravity_result

Poll task status and retrieve the final JSON response

antigravity_cancel

Stop a running task and its child processes

The bridge supports Windows, macOS, and Linux. It has no npm dependencies and does not read or copy authentication credentials.

Related MCP server: Codex Antigravity Subagent MCP

Requirements

  • Node.js 18 or newer

  • Codex CLI or the Codex desktop app with CLI access

  • Google Antigravity CLI installed and authenticated

  • Git, if installing from the repository

Install Antigravity CLI from the official download page, then run agy interactively once to complete Google sign-in. Headless runs use the credentials cached by the official CLI.

Quick installation

Clone the repository and test it:

git clone https://github.com/BerryUIKI/AGY_MCP_CODEX.git
cd AGY_MCP_CODEX
npm test

On Windows PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

On macOS or Linux:

sh ./scripts/install.sh

The installer detects Node.js and agy, replaces an existing Codex MCP entry with the same name, and registers this repository's server.mjs. Restart Codex after installation.

To use a nonstandard CLI path on Windows:

.\scripts\install.ps1 -AntigravityCliPath "C:\path\to\agy.exe"

On macOS or Linux:

ANTIGRAVITY_CLI_PATH=/path/to/agy sh ./scripts/install.sh

Let an agent install it

PROMPTS.md contains ready-to-paste prompts for full installation, configuration of an existing clone, analysis tasks, authorized code edits, follow-up conversations, and cancellation.

SYSTEM_PROMPT.md provides a complete Lead Agent system prompt. It makes the primary agent responsible for task design, Antigravity delegation, independent verification, and final acceptance.

The shortest setup prompt is:

Install and configure AGY_MCP_CODEX from https://github.com/BerryUIKI/AGY_MCP_CODEX.git as a user-level Codex MCP server named "antigravity". Check Git, Node.js 18+, Codex CLI, and `agy`; clone the repository; run `npm test`; run the correct script in `scripts/`; verify with `codex mcp get antigravity --json`; and perform a safe plan-mode test that replies exactly AGY_MCP_OK. If Google sign-in is required, ask me to run `agy` interactively. Never handle my credentials or disable Antigravity permissions.

Manual configuration

Codex stores user-level MCP configuration in ~/.codex/config.toml. The recommended way to update it is through Codex CLI:

codex mcp add antigravity --env ANTIGRAVITY_CLI_PATH=/absolute/path/to/agy -- /absolute/path/to/node /absolute/path/to/AGY_MCP_CODEX/server.mjs

Verify or remove the registration:

codex mcp get antigravity --json
codex mcp remove antigravity

If ANTIGRAVITY_CLI_PATH is omitted, the bridge searches the platform's normal installation location and PATH.

Usage

After restarting Codex, ask:

Use the Antigravity MCP to analyze the project at C:\work\my-project. Run in plan mode, investigate the failing build, and return likely causes with evidence. Poll until the task finishes.

For an edit you explicitly authorize:

Use the Antigravity MCP to fix the failing build in C:\work\my-project. I authorize edits inside that project. Use accept-edits mode, preserve unrelated changes, run relevant tests, and poll until completion. Then inspect the diff and summarize it.

antigravity_start accepts:

Argument

Meaning

prompt

Required task instructions, up to 12,000 characters

cwd

Required existing absolute project directory

mode

plan by default, or accept-edits for authorized edits

model

Optional Antigravity model override

conversation_id

Optional prior conversation to continue

timeout_seconds

10–1,800 seconds; default 300

Only one task runs at a time in each MCP process. Up to 30 recent task records remain in memory and are cleared when Codex restarts the server. Poll antigravity_result about every 10 seconds.

Security model

  • The bridge never passes --dangerously-skip-permissions.

  • Antigravity retains its own permission and sandbox behavior.

  • cwd must be an existing absolute directory.

  • Arguments are passed directly to the executable without a shell.

  • Output is capped at 2 MB; diagnostics retain only the latest 12 KB.

  • Cancelling a task stops its process tree but does not revert changes already written.

  • Credentials remain under the official Antigravity CLI's authentication system.

Because MCP clients can invoke powerful tools, review the task prompt and working directory before authorizing file-changing work.

Troubleshooting

installed: false from antigravity_status

Install agy, add it to PATH, or reinstall the MCP entry with ANTIGRAVITY_CLI_PATH set to the executable's absolute path.

authentication required

Run agy in a terminal, complete Google sign-in, exit the interactive session, and retry from Codex. Do not paste authorization codes into an agent chat.

Tools do not appear in Codex

Run codex mcp get antigravity --json, confirm that the entry is enabled, then restart Codex so the MCP server is loaded in a new session.

A file operation needs approval or fails in headless mode

Antigravity's normal permission policy still applies. Grant only the specific operations required for the task through Antigravity's own configuration, then retry. The bridge intentionally offers no permission-bypass option.

Development

Run the protocol and validation smoke test:

npm test

The test verifies MCP initialization, tool discovery, CLI status shape, and rejection of invalid working directories, modes, and task IDs. A real model request requires an authenticated Antigravity account and is intentionally excluded from automated tests.

References

License

MIT

Available Tools

4 tools
antigravity_cancelA

Stop a running Antigravity task and its child processes. File changes already completed by the task are not reverted.

Inputs: task_id (required).

antigravity_resultA
Read-only

Read a task status and final Antigravity JSON response. Poll running tasks about every 10 seconds. The response includes a conversation_id that can be passed to a later task. Task records are cleared when the MCP server restarts.

Inputs: task_id (required).

antigravity_startA

Delegate a task to the local Antigravity CLI. An authenticated CLI and an existing absolute working directory are required. Returns a task_id immediately; poll antigravity_result. Use plan for analysis and accept-edits only when file edits are intended. The bridge never bypasses Antigravity permissions.

Inputs: cwd (required), prompt (required), mode, model, +2 more.

antigravity_statusA
Read-only

Check whether the local Antigravity CLI can be found and list tasks held by this MCP process. Authentication is verified only when a task runs.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a distinct role in the task lifecycle, but antigravity_status and antigravity_result both surface task status information, which could cause minor confusion. Overall, the purposes are separable: one checks CLI availability and process-held tasks, the other reads a specific task's status and response.

    Naming Consistency5/5

    All tools follow the consistent antigravity_<verb> pattern with clear, predictable names: status, start, result, cancel. No mixed conventions or vague verbs.

    Tool Count5/5

    Four tools cover the essential operations for delegating and managing tasks through a CLI bridge. The scope is tight and each tool earns its place.

    Completeness5/5

    The tool surface covers the full task lifecycle: initiate (start), monitor/retrieve output (result), terminate (cancel), and environment/process health (status). No obvious dead ends or missing operations for the stated purpose.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • codex-antigravity-mcp

      Lucemz
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables Codex users to delegate engineering, refactoring, auditing, and test execution tasks to Google Antigravity CLI as a persistent autonomous subagent, with tools for managing sessions and running prompts.
      1
      MIT

    • antigravity-plugin-codex

      irrumi
      A
      license
      B
      quality
      C
      maintenance
      Enables a local Codex chat to ask a second opinion, review staged, unstaged, or revision-based diffs, and delegate coding tasks to the Antigravity CLI running in isolated or disposable workspaces. Supports starting, polling, retrieving, and cancelling tasks with returned answers, diffs, changed-file lists, exit codes, and time/output limits, while never auto-applying returned patches.
      8
      1
      MIT