Antigravity MCP Server

A powerful "Next-Level" Model Context Protocol (MCP) server that acts as a programmatic bridge for the Google Antigravity Python SDK. It enables real-time AI agent swarms, bidirectional tool proxying, and Human-in-the-Loop execution safety.

📖 Table of Contents

• Features
• Architecture
• API Reference
• Installation
• Quick Start
• Human-in-the-Loop Intercepts

✨ Features

• Real-Time Swarm Communication: Agents dynamically share a "Blackboard" document, keeping their schemas and logic in sync.
• Bidirectional Tool Proxying: Inject your custom application logic as tools directly into the AI agent's execution context.
• Human-in-the-Loop (HitL): Block dangerous terminal actions and file system mutations until user approval is received.
• Feature Pipelines: Spin up specialized Planner, Coder, and Reviewer agents in a unified workflow.

🏛️ Architecture

graph TD;
    Client[Your Application] -->|JSON-RPC| MCPServer[FastAPI MCP Server];
    MCPServer -->|Tool Proxy| Client;
    MCPServer --> SwarmManager[Swarm Manager Blackboard];
    MCPServer --> HitL[HitL Interceptor];
    HitL -.->|Approval Required| Client;
    SwarmManager --> Agent1[Agent 1: Coder];
    SwarmManager --> Agent2[Agent 2: Reviewer];
    Agent1 --> AntigravitySDK[Google Antigravity SDK];
    Agent2 --> AntigravitySDK;

🔌 API Reference

Model Management & Limits

• GET /models: Lists available models, their benchmarks (MMLU), and token costs
• POST /select_model: Selects the active model for a session
• GET /usage_limits: Checks the usage limit (5-hour constraints and weekly tokens)

Agent Lifecycle Management

• POST /spawn_session: Creates a new agent session with capabilities
• GET /list_sessions: Returns active sessions
• DELETE /kill_session/{session_id}: Terminates an agent

Interaction & Execution

• POST /send_prompt/{session_id}: Sends a task to an agent
• GET /get_transcript/{session_id}: Fetches conversation history

Multi-Agent Swarms & Communication

• POST /run_feature_pipeline: Triggers Planner -> Coder -> Reviewer workflow
• POST /broadcast_update/{session_id}: Updates all agents about schema/state changes
• GET /read_blackboard: Retrieves the global swarm state

Bidirectional Tool Proxying

• POST /register_client_tool: Injects a custom app tool into the agent
• POST /handle_tool_callback/{callback_id}: Returns the tool execution result from your app back to the agent

Human-in-the-Loop (HitL) Safety

• POST /approve_action/{action_id}: Allows a paused/blocked action to proceed
• POST /reject_action/{action_id}: Rejects an action and sends feedback to the agent

Artifact Integration (Resources)

• GET /agent/{session_id}/artifacts/list: Lists all markdown artifacts
• GET /agent/{session_id}/artifacts/{artifact_id}: Retrieves specific artifact content
• GET /agent/{session_id}/artifacts/implementation_plan: Direct access to the design plan
• GET /agent/{session_id}/artifacts/walkthrough: Direct access to the completion summary

🛠️ Installation

# Clone the repository
git clone https://github.com/Inferno-Aditya/antigravity-mcp.git
cd antigravity-mcp

# Install dependencies
pip install -r requirements.txt

🚀 Quick Start

Start the MCP Server on port 8000:

python server.py

The server will mount all standard MCP endpoints (spawn_session, send_prompt, etc.) on localhost:8000.

Spawning a Session via HTTP POST

curl -X 'POST' \
  'http://localhost:8000/spawn_session' \
  -H 'Content-Type: application/json' \
  -d '{
  "capabilities": ["terminal_read", "file_write"],
  "system_prompt": "You are a backend engineering agent."
}'

🛡️ Human-in-the-Loop Intercepts

Whenever an agent attempts a high-risk operation, the MCP server automatically intercepts it.

The agent pauses while you interact with the /approve_action or /reject_action API endpoints, allowing you to review destructive commands before they run.