Antigravity MCP Bridge (Antigravity 2.0 ↔ Gemini Spark)

Programmatically control Google Antigravity 2.0 agents on Windows via Gemini Spark and remote/local MCP clients over Streamable HTTP and stdio transport.

Architecture Overview

Gemini Spark (or Remote MCP Client)
      │
      │ HTTPS Request (Authorization: Bearer <MCP_AUTH_TOKEN>)
      ▼
Tailscale Funnel (Public HTTPS: https://<node>.<tailnet>.ts.net/mcp)
      │
      │ Encrypted Local Tunnel
      ▼
Streamable HTTP MCP Server (src/http_server.py on 127.0.0.1:8000)
      │
      ├── AuthMiddleware (Validates MCP_AUTH_TOKEN -> 401 Unauthorized if invalid)
      ├── /health & /healthz Diagnostic Endpoints
      │
      ▼
FastMCP Core Server (src/server.py - Streamable HTTP & stdio)
      │
      ├── launch_antigravity_agent
      ├── get_session_status
      ├── list_workspace_artifacts
      └── run_antigravity_cli_command
      │
      ▼
Antigravity Bridge Adapter -> agentapi.bat -> Antigravity 2.0 Runtime -> Local Workspace

Related MCP server: tailscale-mcp

Quick Start (Windows One-Click Operations)

• START.bat: Initializes environment, creates .env with secure auth token, starts background HTTP server on 127.0.0.1:8000, enables Tailscale Funnel, and displays connection banner.

• STATUS.bat: Inspects live server health, PID status, auth token state, Tailscale login & Funnel status, and Antigravity runtime availability.

• STOP.bat: Gracefully terminates the HTTP MCP server process and disables Tailscale Funnel mapping.

Key Features

1. Dual Transport Support:

   • Stdio transport for local MCP clients (python src/server.py).

   • Streamable HTTP transport for Gemini Spark and remote clients (START.bat / python -m src.http_server).

2. Authentication & Token Protection:

   • AuthMiddleware enforcing token validation on /mcp.

   • Supports Authorization: Bearer <token>, x-api-key: <token>, or ?token=<token>.

   • Auto-generates 32-character hex token if missing in .env.

3. Tailscale Funnel Integration:

   • Secure public HTTPS endpoint without purchasing a domain.

   • Robust detection, status reporting, and resolution guidance when Tailscale is absent or disabled.

4. Antigravity 2.0 Local Engine:

   • Zero-config integration with local Antigravity Language Server via agentapi.bat.

5. Safety & Workspace Isolation:

   • Workspace boundary validation preventing path traversal attacks.

   • Automatic secret key and token redaction from output streams.

   • Concurrent workspace execution locking preventing multi-agent conflicts.

Exposed MCP Tools

• launch_antigravity_agent: Launches an Antigravity agent task targeting a local workspace.

• get_session_status: Inspects session status, timestamps, and live metadata.

• list_workspace_artifacts: Indexes files, sizes, timestamps, and SHA256 hashes in workspace.

• run_antigravity_cli_command: Executes supported agentapi subcommands (get-conversation-metadata, send-message, new-conversation).

Verification & Test Suite

Run full automated unit and integration tests:

.venv\Scripts\python.exe -m pytest tests/

Run real end-to-end HTTP MCP integration test:

.venv\Scripts\python.exe remote_smoke_test.py

Run local stdio smoke test:

.venv\Scripts\python.exe smoke_test.py

Documentation

Detailed documentation is available in docs/:

• docs/remote-access.md: Complete guide for remote access, Tailscale Funnel, and Gemini Spark connection.

• docs/mcp-setup.md: Client configuration snippets for Gemini Spark and Antigravity IDE.

• docs/security.md: Security model, path validation, and secret redaction rules.

• docs/troubleshooting.md: Troubleshooting matrix and diagnostic recovery steps.

• FINAL-REPORT.md: Complete integration status report and empirical verification matrix.