agy-mcp
This server lets Claude delegate heavy coding, autonomous execution, and expert consultation to Antigravity, OpenAI Codex, and ChatGPT subagents.
Run headless Antigravity agents for large multi-file edits, repo sweeps, refactoring, research, or test suites (
agy_execute) and continue prior conversations (agy_continue).Run autonomous OpenAI Codex agents for coding, terminal commands, script execution, and file edits (
codex_execute) and resume existing threads (codex_continue).Consult ChatGPT for architectural advice, design trade-offs, second opinions, and adversarial reviews of diffs or code (
chatgpt_consult,chatgpt_review).Execute tasks asynchronously to avoid Claude Desktop 60-second timeouts, then poll status and results with
agy_check_taskorcodex_check_task.Track lifetime token savings and inspect step-by-step tool traces/transcripts without bloating context (
agy_get_token_savings,agy_inspect_transcript).Check whether Antigravity and Codex CLIs are installed, responsive, and authenticated (
agy_get_status,codex_get_status).Automatically receive git diff statistics and modified file lists from delegated tasks.
Watch live subagent activity in any terminal via the
watchcommand and~/.agy-mcp/live.jsonlfeed.
Delegates heavy coding, repository exploration, and test execution tasks to Antigravity, a headless agent powered by Google Gemini, with support for async background execution and follow-up conversations.
Provides integration with OpenAI Codex for autonomous coding, refactoring, scripting, and terminal actions, and with ChatGPT for architectural consulting, second opinions, and adversarial code reviews.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agy-mcp Refactor the auth module and run the test suite via agy, then summarize the diff."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Omni-Bridge (agy-mcp)
A Model Context Protocol (MCP) server that transforms Claude Code and Claude Desktop into an omni-agent orchestrator. Claude acts as the lead architect, delegating token-heavy operations and specialized tasks to Antigravity (agy), OpenAI Codex (codex), and ChatGPT subagents.
┌───► Antigravity (`agy_execute`) [Google Gemini]
│ Heavy edits, repository exploration, and long test suites
│
Claude Code / Desktop ───┼───► OpenAI Codex (`codex_execute`) [Codex CLI]
(Lead Architect) │ Autonomous coding, terminal actions, and script executions
│
└───► ChatGPT (`chatgpt_consult`) [OpenAI o3 / GPT-4o]
System design advice, math, and adversarial code reviews🚀 Quick Setup
1. Claude Code CLI (Automatic Updates)
Run once in your terminal:
claude mcp add antigravity npx -y github:josephjerryrhule/agy-mcpOr add directly to ~/.claude.json:
{
"mcpServers": {
"antigravity": {
"command": "npx",
"args": ["-y", "github:josephjerryrhule/agy-mcp"]
}
}
}2. Claude Desktop (Automatic Updates)
Add to your claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"antigravity": {
"command": "npx",
"args": ["-y", "github:josephjerryrhule/agy-mcp"]
}
}
}3. Direct 1-Click .mcpb Download (Claude Desktop)
If you prefer installing a standalone bundle without npm:
👉 Download Latest agy-mcp.mcpb
Double-click the downloaded .mcpb file to import it into Claude Desktop.
Related MCP server: agent-delegation-mcp
🌟 How It Works: Division of Labor
Large coding tasks quickly exhaust Claude's context window. Instead of loading dozens of files or running multi-turn loops directly in Claude, Claude delegates the work:
Claude (The Lead Architect):
Keeps high-level context, architecture, schema design, and strategy.
Formulates explicit, pixel-perfect implementation instructions.
Performs final review and quality assurance.
Antigravity (
agy) (The Volume Execution Engine):Runs headless via Google Gemini (
agy -p --dangerously-skip-permissions).Handles multi-file implementations, wide repo sweeps, boilerplate generation, and iterative test loops.
Returns a concise summary, git diff, and token analytics back to Claude.
OpenAI Codex (
codex) (The Autonomous Coding Agent):Runs headless via OpenAI Codex CLI (
codex exec --dangerously-bypass-approvals-and-sandbox).Reuses your existing ChatGPT subscription (no per-token API billing required).
Executes terminal commands, bash scripts, and code refactors in an isolated workspace.
Has built-in image generation capabilities to create and place project assets.
ChatGPT Consulting (
chatgpt) (The Advisory Specialist):Provides adversarial code reviews on git diffs (security, performance, architecture).
Delivers second opinions on complex algorithms, state machines, and system trade-offs.
✨ Core Features
Real-Time Terminal Telemetry: Colored live progress banners showing active tool calls, thinking tokens, and execution durations.
Exact Token Savings Calculator: Computes exact tokens processed by workers versus tokens returned to Claude, recording lifetime metrics.
Claude Desktop 60-Second Timeout Immunity: Background execution mode (
async: true) with polling (agy_check_task/codex_check_task) prevents Claude Desktop client timeouts on long runs.Automatic Git Intelligence: Automatically returns git diff statistics and modified file lists upon task completion.
Zero-Dependency Standalone Bundle: Pre-compiled with
esbuild. Runs out of the box with zero runtimenode_modules.
🛠️ MCP Tool Reference
🪐 Antigravity Delegation (agy)
agy_execute: Spawns a headless Antigravity subagent for heavy coding, wide exploration, or test runs.instructions(string, required): Step-by-step implementation plan.workspace_dir(string, optional): Target directory (mandatory in Claude Desktop).async(boolean, default:false): Runs in background to avoid 60s client timeouts.effort(enum:low,medium,high, default:high): Reasoning effort.mode(enum:accept-edits,plan, default:accept-edits): Execution mode.timeout_seconds(number, default:600): Execution timeout.include_git_diff(boolean, default:true): Returns modified files and git diff statistics.
agy_continue: Continues an existing Antigravity conversation for follow-up fixes or iterative adjustments.conversation_id(string, required): Prior conversation ID.instructions(string, required): Follow-up feedback or bugfix instructions.workspace_dir(string, optional)async(boolean, default:false)
agy_check_task: Polls the execution status, trace, and final output of an async task (agyorcodex).task_id(string, required): The task ID returned by an async execution.
agy_get_token_savings: Returns lifetime context window tokens saved across all sessions.agy_inspect_transcript: Inspects step-by-step tool actions and responses from a prior conversation log.agy_get_status: Verifies that the Antigravity CLI is installed and responsive.
⚡ OpenAI Codex Delegation (codex)
codex_execute: Spawns an autonomous OpenAI Codex subagent to execute code modifications, scripts, or tests.instructions(string, required): Implementation prompt for Codex.workspace_dir(string, optional): Working directory for execution.async(boolean, default:false): Runs in background (recommended for long runs in Claude Desktop).model(string, default:'gpt-5.6-luna'): Codex model (gpt-5.6-luna,gpt-5.6-terra,gpt-reserve).reasoning_effort(enum:low,medium,high,xhigh, optional): Reasoning effort.sandbox(enum:read-only,workspace-write,danger-full-access, default:danger-full-access)timeout_seconds(number, default:600)include_git_diff(boolean, default:true)
codex_continue: Resumes an existing Codex conversation thread (codex exec resume) for iterative bugfixing.thread_id(string, required): Prior thread ID returned fromcodex_execute.instructions(string, required): Next steps or corrections.workspace_dir(string, optional)async(boolean, default:false)
codex_check_task: Checks background status and results of an async Codex task.task_id(string, required)
codex_get_status: Reports installed Codex CLI version and authentication status.
💬 ChatGPT Consulting & Review (chatgpt)
chatgpt_consult: Consults ChatGPT for high-level technical advice, architectural trade-offs, or second opinions.prompt(string, required): Question or design problem.context(string, optional): Code snippets, log outputs, or requirements.model(string, default:'o3-mini'): Model to consult (o3-mini,gpt-4o,o1).reasoning_effort(enum:low,medium,high, optional): Reasoning effort for o-series models.system_prompt(string, optional): Custom persona or guidance.
chatgpt_review: Performs an adversarial review on a git diff or code snippet.diff_or_code(string, required): Code or git diff to review.focus(enum:security,performance,architecture,thorough, default:thorough): Review focus area.instructions(string, optional): Specific review criteria.model(string, default:'o3-mini')
👀 Live Watch: See Subagent Work in Your Shell
The MCP client swallows the server's stderr, so only Claude sees what a subagent is doing. Every Antigravity, Codex, and ChatGPT task also writes structured events to ~/.agy-mcp/live.jsonl, and watch renders them as threads in any terminal: one thread per task, with its instructions, thinking steps, tool calls, streamed replies, changed files, and a closing status.
alias agywatch='npx -y github:josephjerryrhule/agy-mcp watch' # add to ~/.zshrc once
agywatch # replay running tasks, then follow live
agywatch -n 3 # also replay the last 3 tasks in full
agywatch -t 306388 # one task (id prefix, same id agy_check_task uses)
agywatch -q # steps only, hide streamed text
agywatch --list # table of recent tasks and exit┌ 🟣 antigravity 306388aa 14:02:11
│ 📁 ~/Desktop/dev/site high · accept-edits
│ › Refactor the auth middleware and add expiry tests
│ 👀 working…
│ 🧠 thinking 1,204 tokens · 3.1s +4.0s
│ ⚡ view_file src/auth.ts +6.2s
│ ✓ view_file 0.1s
│ I'll update the middleware now.
│ ± src/auth.ts
└ ✅ SUCCESS 42.8s · 46,963 tokens · 1 file changedWhen several tasks run at once, a ↳ agent id marker shows which thread the next lines belong to. Set AGY_MCP_FEED_DIR to move the feed; it rotates at 20 MB.
📋 Recommended Rules for CLAUDE.md
Add this section to your ~/.claude/CLAUDE.md (or project CLAUDE.md) so Claude automatically knows when and how to delegate:
## Subagent Delegation Guidelines
Claude acts as the Lead Architect / Orchestrator. Delegate execution to specialized subagents:
1. Antigravity (`agy_execute` / `agy_continue`):
- Best for: Reading dozens of files, large multi-file edits, running test suites, or broad repository exploration.
- For operations taking more than 45 seconds in Claude Desktop, use async: true and poll with agy_check_task.
2. OpenAI Codex (`codex_execute` / `codex_continue`):
- Best for: Autonomous coding tasks, script execution, or when OpenAI code models (gpt-5.6-luna, gpt-5.6-terra) excel at the problem.
- Pass thread_id to codex_continue for follow-up adjustments.
3. ChatGPT Consulting (`chatgpt_consult` / `chatgpt_review`):
- Best for: High-level architectural second opinions (o3-mini, gpt-4o) or adversarial security and performance reviews on git diffs.🔧 Building from Source
# Clone the repository
git clone https://github.com/josephjerryrhule/agy-mcp.git
cd agy-mcp
# Install dependencies
npm install
# Compile TypeScript and bundle with esbuild
npm run build
# Package standalone .mcpb bundle for Claude Desktop
npm run bundle:mcpb📄 License
MIT (c) Joseph Jerry Rhule
Available Tools
12 toolsagy_check_taskB
Checks the status, running duration, execution trace, and results of an asynchronous task started with async: true.
Inputs: task_id (required).
agy_continueA
Continues an existing Antigravity conversation for follow-up adjustments, revisions, test fixing, or iterative tasks with real-time streaming and token savings tracking.
Inputs: instructions (required), conversation_id (required), async, effort, +3 more.
agy_executeA
Spins up a headless Antigravity (agy) agent to autonomously execute heavy coding, editing, refactoring, research, or testing tasks with live streaming progress, thinking token logs, tool tracing, and token savings metrics.
Inputs: instructions (required), mode, async, model, +4 more.
agy_get_statusA
Checks whether the Antigravity CLI (agy) is available, responds, and reports current CLI status.
Inputs: no named parameters.
agy_get_token_savingsA
Returns lifetime token savings analytics and history of context window saved across all delegations.
Inputs: no named parameters.
agy_inspect_transcriptB
Inspects the execution trajectory, tool calls, and actions from an Antigravity conversation without filling context with raw logs.
Inputs: conversation_id (required), max_steps.
chatgpt_consultB
Consults ChatGPT / OpenAI models (e.g. o3-mini, gpt-4o, o1) for high-level technical advice, architectural review, edge case analysis, or second opinions.
Inputs: prompt (required), model, context, temperature, +2 more.
chatgpt_reviewC
Requests an adversarial code review from ChatGPT on a git diff, file content, or code snippet with specialized focus.
Inputs: diff_or_code (required), focus, model, instructions.
codex_check_taskB
Checks the status, running duration, execution trace, and results of an asynchronous task (Codex or Antigravity).
Inputs: task_id (required).
codex_continueA
Continues an existing Codex session thread for follow-up adjustments, corrections, or iterative bugfixing.
Inputs: thread_id (required), instructions (required), async, model, +4 more.
codex_executeB
Spins up an OpenAI Codex subagent to autonomously execute coding, refactoring, testing, and file editing tasks with live streaming progress and token savings tracking.
Inputs: instructions (required), async, model, sandbox, +4 more.
codex_get_statusA
Checks whether the OpenAI Codex CLI is installed, operational, and reports current authentication status.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
The agy_* and codex_* families have parallel execute/continue/check/status tools that can be confused, especially since codex_check_task explicitly says it handles both Codex and Antigravity tasks. Prefixes and descriptions help, but the duplicate lifecycle across two similar agent types creates real ambiguity.
All tools follow a consistent provider_prefix + verb pattern using snake_case, such as agy_execute, codex_check_task, and chatgpt_review. This makes the tool set predictable and easy to navigate.
Twelve tools is within a reasonable range for a multi-provider delegation server. The count is slightly inflated by parallel lifecycle tools for agy and codex, but each provider family has a clear purpose.
The tool surface covers the core delegation workflow: execute, continue, check status, inspect transcripts, and get provider status. Minor gaps exist, such as no explicit cancellation or session listing, but agents can complete primary tasks without dead ends.
Maintenance
Related MCP Connectors
Shared long-term memory & Stop-hook task handoff across Claude Code, Codex, Cursor, and mobile.
Hand off work between AI agents in any tool. Start Devin or Cursor cloud and share memory.
Build agents to automate any background task. Works with your ChatGPT/Claude subscription.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude to delegate tasks to external coding agents (Codex or Antigravity) for independent reviews, separate quota usage, and async processing.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code to delegate implementation tasks to Antigravity CLI and OpenCode, run them fully autonomously, and then review and gate the results.1MIT
- AlicenseCqualityBmaintenanceEnables a primary agent in Antigravity IDE to delegate coding tasks to background subagents across multiple model backends, with crash recovery, process cleanup, and human-in-the-loop approval for destructive actions.20MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to delegate tasks to Google Antigravity (Gemini) as an autonomous subagent, including codebase exploration, architecture analysis, multi-file code generation, and technical Q&A, without requiring external API keys.MIT