Antigravity MCP Bridge

A local Model Context Protocol (MCP) server that lets Codex or Claude Code coordinate persistent Antigravity CLI (agy) workers as independent implementers and testers.

The bridge uses stdio, starts child processes without a shell, restricts workers to explicit workspace roots, and records bounded NDJSON audit events locally.

Requirements

• Node.js 20 or newer

• Codex CLI/Desktop or Claude Code

• Antigravity CLI (agy), authenticated for the current user

• Git

Verify the required commands:

node --version
agy --version

Related MCP server: sub-antigravity

Install

git clone https://github.com/Daniiislo/antigravity-mcp-bridge.git
cd antigravity-mcp-bridge
npm ci
npm run build

Register

Choose the directories that Antigravity workers may access, then run one command.

Codex:

npm run register:codex -- --root "C:\Projects" --root "D:\Work"
codex mcp get antigravity-bridge

Claude Code:

npm run register:claude -- --root "C:\Projects" --root "D:\Work"
claude mcp get antigravity-bridge

The same commands work on macOS and Linux with POSIX paths:

npm run register:codex -- --root "$HOME/Projects"
# or
npm run register:claude -- --root "$HOME/Projects"

To allow complete Windows drives instead:

npm run register:codex -- --root "C:\" --root "D:\"

Open a new Codex task or restart Claude Code after registration.

--root may be repeated. Use a project folder for tighter access or a drive root for every directory on that drive. Both installers automatically discover their host CLI, agy, and Node.js. Claude Code registration uses the global user scope.

Controller API

The preferred asynchronous workflow is:

create_worker → dispatch_task → wait_task / agy_events
              → inspect_task → send_followup → close_worker

Four compatibility tools remain available: agy_delegate, agy_status, agy_stop, and agy_reset.

Configuration

The registration installer writes environment variables into the host MCP configuration. The server does not automatically load .env files. See .env.example in the source repository for a reference template.

Safety properties

• Commands use argument arrays with shell: false.

• Workspace paths are canonicalized and checked against AGY_ALLOWED_ROOTS.

• wait_task is capped at 30 seconds.

• Inspection, stderr, model output, and persisted fields are bounded.

• Environment variables are excluded from event logs.

• Empty SUCCESS responses and denied actions remain visible as failures or diagnostics.

• Runtime logs, scratch files, dependencies, build output, and secrets are excluded from Git.

Update

git pull
npm ci
npm test
npm run build
codex mcp remove antigravity-bridge
npm run register:codex -- --root "/path/to/projects"

For Claude Code, replace the two commands above with claude mcp remove antigravity-bridge --scope user and npm run register:claude -- ....

Registration is replaced as a whole. Include every allowed root when registering again.

Remove

codex mcp remove antigravity-bridge

Claude Code:

claude mcp remove antigravity-bridge --scope user

This removes the MCP registration but does not delete the repository or local run logs.

Troubleshooting

• agy not found: install and authenticate agy, add it to PATH, or pass --agy-bin.

• Workspace rejected: register its canonical parent directory with --root.

• Tools missing: verify registration, then start a new Codex task or restart Claude Code.

• Registration exists: remove the existing entry before registering again.

• Action denied: grant only the narrow Antigravity permission required by the task.

Development

npm test
npm run typecheck
npm run smoke
npm audit --audit-level=high
npm pack --dry-run

CI runs these checks on Windows and Ubuntu with Node.js 20 and 22.

License

MIT. See LICENSE.