Antigravity Orchestrate MCP Server (orchestrate-agy-mcp)

An MCP (Model Context Protocol) server designed to manage, orchestrate, and run Antigravity (agy.exe) coding agent tasks in the background on Windows.

By leveraging pseudo-terminals (node-pty), this server spawns agent jobs asynchronously, monitors their progress, supports failover configurations (e.g. rate limit/quota fallback), and reports status/output updates back to the parent agent. This enables sequential or parallel multi-agent task execution without blockages.

---

Features

• 🚀 Background Execution (run_agy): Spawns agy.exe non-interactively using -p/--print inside a node pseudo-terminal (PTY) environment.
• 🔄 Conversation Resumption (continue_agy): Resumes the most recent or a specific agy conversation session (via -c or --conversation) to supply follow-up feedback.
• ⏱️ Non-blocking Polling & Waiting (wait_for_agy): Optimizes token usage and avoids MCP RPC timeouts by allowing clients to poll execution progress in short intervals (~5s) rather than holding the connection open indefinitely.
• 🛡️ Model Failover & Account Swapping:
  • Automatically detects API quota/rate-limiting errors (e.g., 429, resource_exhausted).
  • Fallbacks from Gemini to Claude (or vice-versa).
  • Can trigger a local PowerShell script (switch-account.ps1) to swap API credentials seamlessly when a secondary failover is needed.
• 📝 Git Summary Reports: Automatically appends a summary of modified/added files and git diff --stat output to the final log once an agent task completes.
• 🧹 ANSI Escape Cleanups: Automatically sanitizes VT100/ANSI terminal color and cursor codes from output buffers to guarantee human-readable plain text logs.

---

Project Structure

mcp-server/
├── .gitignore                   # Excludes node_modules, build outputs, local logs, and state
├── README.md                    # Project documentation
└── agy-mcp-server/              # Source code directory
    ├── package.json             # Dependencies and scripts
    ├── tsconfig.json            # TypeScript configuration
    ├── src/
    │   ├── index.ts             # MCP server initialization & tool handlers
    │   └── JobManager.ts        # Pseudo-terminal management, watchdog timers, failover handling
    ├── test-job-completes.mjs   # Integration check for job completion
    ├── mcp-continue-probe.mjs   # End-to-end check for run -> continue flow
    └── mcp-crash-probe.mjs      # Server stability & stderr error monitoring probe

---

Installation & Build

Prerequisites

• Node.js (v18+ recommended)
• Antigravity CLI (agy.exe) installed on the system path.

Build Steps

1. Navigate into the agy-mcp-server directory:

   cd agy-mcp-server
   

2. Install dependencies:

   npm install
   

3. Compile the TypeScript source code:

   npm run build
   

---

Configuration

To add this server to your local Claude Desktop or other MCP-compatible clients, append the configuration to your settings file (e.g., C:/Users//.claude/settings.json):

{
  "mcpServers": {
    "orchestrate-agy": {
      "command": "node",
      "args": [
        "G:/workspace/mcp-server/agy-mcp-server/dist/index.js"
      ],
      "env": {
        "PATH": "C:\\Users\\\\AppData\\Local\\agy\\bin;C:\\Windows\\system32;C:\\Windows;C:\\Program Files\\nodejs",
        "DEFAULT_CWD": "G:/workspace",
        "DEFAULT_MODEL": "Gemini 3.5 Flash (Medium)",
        "MAX_JOB_RUNTIME_MS": "1800000"
      }
    }
  }
}

Environment Variables

• DEFAULT_CWD: Default folder where agy.exe will run if no path is supplied.
• DEFAULT_MODEL: Default LLM utilized for task execution (e.g. 'Gemini 3.5 Flash (Medium)').
• MAX_JOB_RUNTIME_MS: Time limit (in milliseconds) before a job is automatically terminated by the watchdog (default is 30 minutes).

---

MCP Tools Reference

---

Testing & Probes

The repository includes scripts to test the MCP server functionality:

• test-job-completes.mjs: Verifies that a dispatched agy task executes, exits cleanly, and is marked completed (rather than hanging).
• mcp-continue-probe.mjs: Confirms that continue_agy resumes the correct, most recent session and retains previous context (e.g., remembering secrets).
• mcp-crash-probe.mjs: Validates the JSON-RPC interface and ensures the background process stays alive during standard exception handling and git summaries.