Antigravity Codex MCP

A controlled Model Context Protocol bridge that lets OpenAI Codex delegate work to Google Antigravity CLI on demand.

The bridge stays idle until a user explicitly asks Codex to use AGY. It then authorizes only the exact current project, keeps a project-scoped conversation, synchronizes user-visible dialogue, and confines generated implementation changes to an isolated copy.

This is an independent community project. It is not affiliated with or endorsed by Google or OpenAI.

中文说明

Highlights

• Explicit opt-in: Codex cannot enable or call AGY unless the user asks for it.

• Exact project scope: broad roots and system directories are rejected.

• Read-only delegation by default: no AGY write, command, URL, or MCP permission is granted.

• Project conversations: active conversation IDs and delegation history survive new Codex tasks.

• Visible transcript sync: messages entered through AGY CLI become available to Codex on the next sync.

• Private-reasoning filter: thinking/reasoning fields, system messages, and checkpoints are excluded before persistence or MCP return.

• Isolated implementation: validated full-file replacements are applied only to a disposable project copy.

• Auditable runs: responses, changed-file manifests, verification output, and sanitized tool events are retained locally.

Requirements

• Node.js 20 or newer

• Antigravity CLI

• OpenAI Codex with MCP support

Authenticate Antigravity CLI and verify that agy is available:

agy --version
agy -p "Reply exactly: AGY_OK" --output-format json

If agy is not on PATH, set AGY_BIN to its executable path in the MCP configuration.

Installation

git clone https://github.com/ustc-fyk/antigravity-codex-mcp.git
cd antigravity-codex-mcp
npm ci
npm test

Add the server to your Codex config.toml. Replace the example paths with the absolute clone path on your machine:

Linux / macOS:

[mcp_servers.antigravity]
command = "node"
args = ["/path/to/antigravity-codex-mcp/src/index.js"]
cwd = "/path/to/antigravity-codex-mcp"
enabled = true
required = false
startup_timeout_sec = 20
tool_timeout_sec = 900
default_tools_approval_mode = "prompt"
enabled_tools = [
  "antigravity_health",
  "antigravity_project_status",
  "antigravity_enable_project",
  "antigravity_disable_project",
  "antigravity_start_session",
  "antigravity_get_active_session",
  "antigravity_list_sessions",
  "antigravity_sync_conversation",
  "antigravity_get_transcript",
  "antigravity_ask",
  "antigravity_continue",
  "antigravity_review",
  "antigravity_execute",
  "antigravity_list_runs",
  "antigravity_get_run",
]

# Optional when agy is not available on PATH:
# [mcp_servers.antigravity.env]
# AGY_BIN = "/path/to/agy"

Windows:

[mcp_servers.antigravity]
command = "node"
args = ['C:\path\to\antigravity-codex-mcp\src\index.js']
cwd = 'C:\path\to\antigravity-codex-mcp'
enabled = true
required = false
startup_timeout_sec = 20
tool_timeout_sec = 900
default_tools_approval_mode = "prompt"
enabled_tools = [
  "antigravity_health",
  "antigravity_project_status",
  "antigravity_enable_project",
  "antigravity_disable_project",
  "antigravity_start_session",
  "antigravity_get_active_session",
  "antigravity_list_sessions",
  "antigravity_sync_conversation",
  "antigravity_get_transcript",
  "antigravity_ask",
  "antigravity_continue",
  "antigravity_review",
  "antigravity_execute",
  "antigravity_list_runs",
  "antigravity_get_run",
]

# Optional when agy is not available on PATH:
# [mcp_servers.antigravity.env]
# AGY_BIN = 'C:\path\to\agy.exe'

Install the included Codex Skill so Codex follows the opt-in workflow:

Linux / macOS (Bash):

mkdir -p ~/.codex/skills/agy-project-assistant
cp ./skills/agy-project-assistant/SKILL.md ~/.codex/skills/agy-project-assistant/

Windows (PowerShell):

$skillRoot = Join-Path $env:USERPROFILE ".codex\skills\agy-project-assistant"
New-Item -ItemType Directory -Force $skillRoot | Out-Null
Copy-Item ".\skills\agy-project-assistant\SKILL.md" $skillRoot

Restart Codex after changing MCP configuration or installing the Skill.

Usage

1. Open any project directory in Codex.

2. Work normally; the AGY bridge remains idle.

3. Explicitly ask: Load AGY and review this project.

4. Codex enables read access for that exact project and starts or reuses its AGY conversation.

5. Codex delegates analysis, review, continuation, or isolated implementation as appropriate.

6. Ask Disable AGY for this project to revoke the exact project permission while preserving local audit history.

To inspect or participate in the same conversation directly:

agy --conversation=<conversation_id>

After sending messages through AGY CLI, ask Codex to sync the AGY conversation. antigravity_continue also synchronizes before and after every follow-up. Synchronization is on demand, not a live push channel, so avoid simultaneous sends from Codex and AGY CLI.

MCP tools

Model calls occur only through the start, ask, continue, review, and execute tools. Health, status, history, run inspection, and transcript synchronization do not consume an AGY model turn.

Project-local state

Each enabled project receives an ignored local state directory:

.antigravity-mcp/
├── project.json
├── sessions.jsonl
├── transcripts/
│   └── <conversation-id>.jsonl
└── runs/
    └── <run-id>/
        ├── metadata.json
        ├── events.jsonl
        ├── response.md
        └── workspace/

• project.json records opt-in state and the active conversation.

• sessions.jsonl records delegated calls and token usage.

• transcripts contains only visible user/assistant records and sanitized tool traces.

• runs contains isolated implementation workspaces and audit results.

This directory is excluded from the source copy and ignored by Git. Do not commit it manually because it may contain private project or conversation data.

Safety model

Project enablement atomically adds only the exact root to Antigravity trustedWorkspaces and read_file(...) allow rules. Disablement removes only those exact entries.

Isolated implementation rejects:

• absolute paths and parent traversal;

• file deletion;

• secret files, dependencies, build output, metadata, and symbolic links;

• more than 50 changed files;

• more than 2,000,000 replacement characters.

Any dependency, cache, virtual-environment, build, or metadata directory is excluded at every nesting depth, including monorepo packages. Project-local state uses a managed * rule so project.json, sessions.jsonl, runs, and transcripts are all ignored by Git.

Verification is an explicit high-risk operation: a non-none verification value also requires allow_untrusted_verification: true. Commands such as npm test or pytest execute code from the AGY-influenced isolated workspace. The isolated directory protects the source tree, but it is not an OS security sandbox. The combined AGY and verification timeout budget is capped below the recommended 900-second MCP timeout.

AGY and verification timeouts terminate the full spawned process tree. Health checks have a 15-second default timeout and a 64 KiB output limit. Settings locks contain PID/timestamp metadata and dead-process locks are recovered automatically.

The transcript pipeline recursively removes private reasoning fields and excludes system/checkpoint records before writing the project mirror. See SECURITY.md for reporting guidance and limitations.

Operator environment variables

• AGY_BIN: AGY executable path; defaults to agy on PATH.

• AGY_HEALTH_TIMEOUT_MS: health-check timeout, clamped to 100–60,000 ms.

• ANTIGRAVITY_SETTINGS_PATH: override the AGY settings file path.

• ANTIGRAVITY_CLI_DATA_DIR: override the AGY CLI data root used for transcript lookup.

• ANTIGRAVITY_ALLOWED_ROOTS: static path-delimited root fence in addition to dynamic project authorization.

• ANTIGRAVITY_USE_SANDBOX: request AGY CLI's optional sandbox mode.

• ANTIGRAVITY_PASSTHROUGH_ENV: comma-separated extra environment-variable names. Names that look sensitive are rejected by default.

• ANTIGRAVITY_ALLOW_SENSITIVE_ENV_PASSTHROUGH: high-risk override for sensitive extra names; use only after explicit risk acceptance.

Development

npm ci
npm test
npm run smoke:mcp

Live checks require an authenticated AGY CLI and consume model quota:

npm run smoke:live
npm run smoke:execute
npm run smoke:project -- "/absolute/path/to/disposable-project"
npm run smoke:continue -- "/absolute/path/to/enabled-project"
npm run smoke:transcript -- "/absolute/path/to/enabled-project"

npm test is self-contained. smoke:mcp also checks the local AGY binary, while the remaining smoke tests may change project authorization or consume quota.

License

MIT