`mcp-agy` — Google Antigravity FastMCP Server

Bridging High-Level AI Architect Agents with Autonomous Antigravity Coding Workers via Model Context Protocol (MCP)

🌟 1. Overview & High-Level Vision

In contemporary AI-assisted software engineering, single-agent workflows frequently suffer from cognitive overload, context exhaustion, and execution drift. Large Language Models forced to simultaneously handle macro-level system architecture, cross-module requirements, and low-level line-by-line code editing often lose sight of overarching design invariants.

mcp-agy establishes a paradigm shift: the Architect-Worker Division of Labor.

+-----------------------------------------------------------------------------------+
|                           THE ARCHITECT-WORKER PARADIGM                           |
+-----------------------------------------------------------------------------------+
|                                                                                   |
|   STRATEGIC TIER (The Architect)                                                  |
|   - Claude Desktop, Cursor Composer, Cline, Roo Code                              |
|   - Responsibilities: System design, domain modeling, security audit, code review |
|                                                                                   |
|                                       │                                           |
|                                       │  Delegates via FastMCP JSON-RPC 2.0       |
|                                       ▼                                           |
|                                                                                   |
|   TACTICAL EXECUTION TIER (The Worker)                                            |
|   - Google Antigravity (AGY)                                                      |
|   - Responsibilities: Multi-file edits, build runs, test executions, git diffs    |
|                                                                                   |
+-----------------------------------------------------------------------------------+

Key Pillars:

Separation of Concerns: The AI Architect focuses on reasoning, design trade-offs, and verification. Google Antigravity (AGY) operates as a high-speed execution sandbox performing atomic edits, shell commands, and automated test runs.
Pristine Stdio Protocol Purity: Standard output (sys.stdout) is strictly reserved for JSON-RPC 2.0 frames. All logging, startup banners, and diagnostic traces route exclusively to sys.stderr, preventing framing corruption in MCP clients.
Resilient 3-Tier Backend Fallback: Seamlessly transitions across Python SDK (Tier 1), Subprocess CLI (Tier 2), and High-Fidelity Simulation Mock (Tier 3) for continuous offline testing and CI workflows.
Zero-Trust Workspace Isolation: Path canonicalization, system-critical directory protection, and per-workspace asynchronous mutex concurrency locking prevent race conditions and unintended file modifications.
Pluggable Worker Reasoning Protocol: Optional delivery of the AI Deep Reasoning Toolkit into each workspace, constraining how the worker writes code while leaving the architect's own behaviour untouched. See §6.

🏗️ 2. System Architecture & Data Flow

+-------------------------------------------------------------------------------+
|                       External AI Architect Agent                             |
|          (Claude Desktop, Cursor Composer, Cline, Roo Code, Custom)           |
+---------------------------------------+---------------------------------------+
                                        |
                                        | JSON-RPC 2.0 over Stdio (Pure Stream)
                                        | (Zero stdout pollution; logs to stderr)
                                        v
+---------------------------------------+---------------------------------------+
|                               mcp_agy (FastMCP)                               |
|                                                                               |
|   +--------------------+  +------------+  +--------------+  +-------------+   |
|   | agy_execute_task   |  |  agy_chat  |  | agy_get_diff |  |agy_run_tests|   |
|   +---------+----------+  +-----+------+  +-------+------+  +------+------+   |
|             |                   |                 |                |          |
|             v                   v                 |                |          |
|   +---------+-------------------+------+          |                |          |
|   |          Backend Manager           |          |                |          |
|   |  - Tier 1: PythonSDKBackend        |          |                |          |
|   |  - Tier 2: SubprocessCLIBackend    |          |                |          |
|   |  - Tier 3: MockAGYBackend (CI)     |          |                |          |
|   |  - 3-Tier Fallback Hierarchy       |          |                |          |
|   +-----------------+------------------+          |                |          |
|                     |                             |                |          |
|                     |                             v                v          |
|                     |                    +--------+----+  +--------+------+   |
|                     |                    | Diff Engine |  |  Test Runner  |   |
|                     |                    | - Git diff  |  | - 13 Tiers    |   |
|                     |                    | - Untracked |  | - Auto-Detect |   |
|                     |                    | - Stats     |  | - Diagnostics |   |
|                     |                    +--------+----+  +--------+------+   |
|                     |                             |                |          |
|                     +-----------------------------+----------------+          |
|                                                   |                           |
|                                                   v                           |
|                                      +------------+------------+              |
|                                      | Workspace Safety Engine |              |
|                                      | - Path Canonicalization |              |
|                                      | - Boundary Validation   |              |
|                                      | - Async Concurrency Lock|              |
|                                      +------------+------------+              |
+---------------------------------------------------|---------------------------+
                                                    |
                                                    v
+---------------------------------------------------+---------------------------+
|                              Target Workspace Directory                       |
|   - Multi-file source code, git repository, virtual environments, tests       |
+-------------------------------------------------------------------------------+

Core Subsystems:

FastMCP Server (server.py): High-performance asynchronous stdio MCP server exposing 4 rich tools with strict parameter validation and stderr logging.
Backend Manager (backend_manager.py): Dynamic fallback coordinator orchestrating execution across Python SDK, Subprocess CLI, and offline Simulation Mock.
NDJSON Stream Telemetry Engine (cli_backend.py): Real-time event parsing for tool calls, thought streams, and token consumption metrics.
Git Unified Diff Engine (diff_engine.py): Comprehensive diff capturing tracked modifications, staged files, and newly created untracked files.
Multi-Ecosystem Test Runner (test_runner.py): 13-tier test framework detector (pytest, unittest, npm, cargo, go, gradle, maven, dotnet, etc.) with ANSI color stripping and structured regex diagnostics.
Workspace Safety Engine (workspace.py): Realpath canonicalization, boundary validation, system root blocking, and async mutex locking per workspace.

📦 3. Installation & Prerequisites

Prerequisites:

Operating System: Windows 10/11, macOS 12+, Linux (Ubuntu 20.04+, Debian, Arch, Fedora)
Python: Version 3.10, 3.11, or 3.12+
Package Manager: uv (strongly recommended) or pip
Git: Version 2.20+ (for unified diff engine and repository tracking)
Google Antigravity: Antigravity CLI (agy) installed and authenticated, or google-antigravity Python SDK (offline simulation mock runs automatically if not present).

Quick Installation:

# Clone the repository
git clone https://github.com/google/mcp-agy.git
cd mcp-agy

# Create virtual environment and install in editable mode using uv
uv venv
uv pip install -e .

# Or using standard pip:
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate
pip install -e .

🧰 4. Complete Tool Suite Reference

mcp-agy exposes 8 tools tailored for AI Architect agents: 4 synchronous ones that answer
within a call, and 4 that run AGY as a background job so a long task never has to fit inside
one.

Which to reach for. agy_execute_task and agy_chat block until AGY is done, so they only
work for runs shorter than your client's per-call timeout — 60 seconds on Claude Code. For
anything larger, and that is most real work, start a job:

agy_start_task(workspace, prompt)          -> {"job_id": "...", "status": "running"}   # returns at once
   … the architect keeps working …
agy_job_status(job_id, wait_seconds=30)    -> {"status": "completed", "result": {...}} # collect
agy_get_diff(workspace)                    -> review what AGY actually changed
agy_run_tests(workspace)                   -> verify it

agy_job_status with wait_seconds returns the instant the job finishes, so a short job needs
no polling loop and a long one costs one cheap call per check. The recommended waiting pattern is
monitoring done_marker_path on disk (e.g. until [ -f <path> ]; do sleep 5; done) and calling
agy_job_status(job_id, wait_seconds=0). wait_seconds should always be kept strictly below your
client's per-call timeout: a call with wait_seconds=300 cut by a 60s client timeout will tear down
and restart the server process. Completed job results are atomically persisted to disk before .done
markers appear, so finished jobs survive server restarts and return with recovered_from_disk=True.

Tool Name	Parameter	Type	Required	Default	Description
`agy_start_task`	`workspace_path`	`str`	Yes	—	Target workspace. Returns a `job_id` immediately; AGY keeps running in the server.
	`prompt`	`str`	Yes	—	Self-contained instructions for AGY.
	`auto_approve`	`bool`	No	`True`	Auto-approve AGY's tool executions and file edits.
	`mode`	`Literal["accept-edits", "plan"]`	No	`"accept-edits"`	`"plan"` is the read-only form — the long-running equivalent of `agy_chat`.
	`timeout_seconds`	`int`	No	`600`	Bounds the run, not this call (1 to 3600).
	`rigor`	`Literal["standard", "deep", "off"]`	No	`"standard"`	Reasoning protocol for the run. Inert unless `MCP_AGY_TOOLKIT_PATH` is set — see §6.
`agy_job_status`	`job_id`	`str`	Yes	—	Id returned by `agy_start_task`.
	`wait_seconds`	`int`	No	`0`	Block up to N seconds, returning early on completion. Capped at 45 so the call always fits inside a client timeout.
`agy_cancel_job`	`job_id`	`str`	Yes	—	Stops the run and kills its process tree. Not a rollback — files already written stay written.
`agy_list_jobs`	—	—	—	—	Every known job, newest first, without their results. The recovery path when a `job_id` has fallen out of context; collect a result with `agy_job_status`.

And the 4 synchronous tools:

Tool Name	Parameter	Type	Required	Default	Description
`agy_execute_task`	`workspace_path`	`str`	Yes	—	Target workspace path where AGY will execute coding tasks. Must be an existing directory.
	`prompt`	`str`	Yes	—	Comprehensive coding instructions, file paths, requirements, and constraints.
	`auto_approve`	`bool`	No	`True`	Automatically approve tool executions and file edits without interactive confirmation.
	`mode`	`Literal["accept-edits", "plan"]`	No	`"accept-edits"`	`"accept-edits"` for full file modifications; `"plan"` for read-only analysis without disk writes.
	`timeout_seconds`	`int`	No	`600`	Maximum execution duration in seconds (1 to 3600). Enforces process tree termination on timeout.
	`rigor`	`Literal["standard", "deep", "off"]`	No	`"standard"`	Reasoning protocol for the run. Inert unless `MCP_AGY_TOOLKIT_PATH` is set — see §6.
`agy_chat`	`prompt`	`str`	Yes	—	Analytical query, codebase question, architecture review, or planning consultation.
	`workspace_path`	`str`	No	`""`	Optional workspace directory to provide codebase context for analysis (strictly read-only).
	`conversation_id`	`str`	No	`""`	UUID of a previous conversation session to maintain multi-turn dialogue context.
	`timeout_seconds`	`int`	No	`300`	Maximum consultation duration in seconds (1 to 1800).
`agy_get_diff`	`workspace_path`	`str`	Yes	—	Target workspace repository directory to inspect for git and file modifications.
`agy_run_tests`	`workspace_path`	`str`	Yes	—	Target workspace directory where test suites will be discovered and executed.
	`test_command`	`str`	No	`""`	Optional explicit test command (e.g. `pytest tests/ -v`, `cargo test`). If empty, auto-detects from 13 supported tiers.
	`timeout_seconds`	`int`	No	`300`	Maximum test execution duration in seconds (1 to 1800).

Detailed Return Schemas

1. `TaskExecutionResult` (from `agy_execute_task`)

{
  "status": "success",
  "conversation_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "response": "Implemented JWT authentication module in src/auth.py and created unit tests in tests/test_auth.py.",
  "modified_files": [
    "src/auth.py",
    "tests/test_auth.py"
  ],
  "diff_summary": "2 file(s) modified (+54, -2)",
  "duration_seconds": 14.82,
  "tokens_used": {
    "input_tokens": 2100,
    "output_tokens": 920,
    "thinking_tokens": 450,
    "cache_read_tokens": 0,
    "total_tokens": 3470
  },
  "backend_used": "sdk",
  "error_details": null,
  "reasoning": {
    "rigor": "standard",
    "toolkit_active": true,
    "toolkit_source": "/home/you/src/ai-deep-reasoning-toolkit",
    "toolkit_revision": "a7236c1",
    "installed": ["GEMINI.md", ".agents/skills/deep-verify"],
    "gate_line": "Simplicity gate: cut _fmt_row, _DEFAULTS; kept parse (LOAD-BEARING: contract rule 3).",
    "deep_verify_declined": false,
    "notes": ""
  }
}

reasoning is null unless the deep reasoning toolkit is configured — see §6.

2. `ChatResult` (from `agy_chat`)

{
  "status": "success",
  "conversation_id": "4a1c5b8e-7e9a-4123-b123-abcdef012345",
  "response": "Based on the codebase analysis, `src/services/billing.py` depends directly on `src/db/raw_queries.py`...",
  "duration_seconds": 3.45,
  "tokens_used": {
    "input_tokens": 1200,
    "output_tokens": 480,
    "total_tokens": 1680
  },
  "backend_used": "cli",
  "error_details": null
}

3. `DiffResult` (from `agy_get_diff`)

{
  "status": "success",
  "has_changes": true,
  "unified_diff": "--- a/src/auth.py\n+++ b/src/auth.py\n@@ -10,6 +10,18 @@\n+class JWTManager:\n+    def generate_token(self, user_id: str) -> str:\n+        ...",
  "changed_files": [
    {
      "path": "src/auth.py",
      "status": "M",
      "insertions": 48,
      "deletions": 2
    }
  ],
  "untracked_files": [
    "tests/test_auth.py"
  ],
  "summary": "1 modified, 1 untracked file(s)",
  "error_details": null
}

4. `TestRunResult` (from `agy_run_tests`)

{
  "status": "passed",
  "exit_code": 0,
  "framework": "pytest",
  "test_command_executed": "pytest tests/ -v",
  "output": "============================= test session starts =============================\ntests/test_auth.py::test_generate_token PASSED\ntests/test_auth.py::test_verify_token PASSED\n============================== 2 passed in 0.45s ==============================",
  "summary": {
    "total": 2,
    "passed": 2,
    "failed": 0,
    "skipped": 0,
    "errors": 0
  },
  "failures": [],
  "duration_seconds": 0.52,
  "error_details": null
}

⚙️ 5. Step-by-Step Client Setup Guides