agy-mcp

MCP server for Antigravity CLI (agy).

Expose Google's Antigravity agent (powered by Gemini) as an MCP tool for any MCP client — OpenClaw, Hermes, Claude Desktop, Cursor, or your own orchestrator.

What it does

agy-mcp wraps the agy CLI and exposes it as a single MCP tool: antigravity_code.

• One-shot execution: Send a prompt, get a response
• Session persistence: Reuse the same agy conversation across multiple tool calls via sessionId
• Auto-continue: Automatically resume the most recent agy conversation with autoContinue: true
• Prompt files: Reference long prompts from files via promptFile path
• Any MCP client: Works with anything that speaks the MCP protocol over stdio

Install

# Install globally
npm install -g agy-mcp

# Or run directly with npx
npx -y agy-mcp@latest

Prerequisites

1. Antigravity CLI installed:
   Follow the official docs or run:

   curl -fsSL https://antigravity.google/cli/install.sh | bash

2. Authenticated: Run agy once interactively to sign in with your Google account.

Usage

Standalone

agy-mcp

The server speaks JSON-RPC 2.0 over stdio. It exposes one tool: antigravity_code.

With Claude Desktop / Cursor / any MCP client

Add to your MCP config:

{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["-y", "agy-mcp@latest"],
      "transport": "stdio"
    }
  }
}

Tool Schema: antigravity_code

Parameter	Type	Required	Description
prompt	string	❌*	The natural language task (or use promptFile)
promptFile	string	❌*	Path to a file containing the prompt. Useful for long prompts or image generation workflows
workFolder	string	❌	Absolute path to working directory
sessionId	string	❌	Reuse the same agy conversation across calls
autoContinue	boolean	❌	Continue the most recent agy conversation (equivalent to agy -c)

* Either prompt or promptFile is required.

Example Calls

Simple one-shot

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "antigravity_code",
    "arguments": {
      "prompt": "Generate a Flutter onboarding screen design",
      "workFolder": "/Users/me/projects/myapp"
    }
  }
}

Using a prompt file (for long prompts or image generation)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "antigravity_code",
    "arguments": {
      "promptFile": "/Users/me/prompts/image-generation.txt",
      "workFolder": "/Users/me/projects/myapp"
    }
  }
}

Auto-continue last session (agy -c)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "antigravity_code",
    "arguments": {
      "prompt": "Iterate on the design — make the background darker",
      "workFolder": "/Users/me/projects/myapp",
      "autoContinue": true
    }
  }
}

Session persistence

// Call 1: Start a design task
{"prompt": "Design a splash screen...", "sessionId": "design-001"}

// Call 2: Iterate on the same design
{"prompt": "Make the background darker...", "sessionId": "design-001"}

// Call 3: Export assets
{"prompt": "Export all assets to assets/ folder", "sessionId": "design-001"}

Session Management

Session Persistence (sessionId)

Pass the same sessionId across multiple calls to resume the same agy conversation:

// Call 1: Start a design task
{"prompt": "Design a splash screen...", "sessionId": "design-001"}

// Call 2: Iterate on the same design
{"prompt": "Make the background darker...", "sessionId": "design-001"}

// Call 3: Export assets
{"prompt": "Export all assets to assets/ folder", "sessionId": "design-001"}

Session mappings are stored in ~/.config/agy-mcp/sessions.json.

Auto-Continue (autoContinue)

Set autoContinue: true to automatically resume the most recent agy conversation (equivalent to running agy -c):

{
  "prompt": "Continue working on the design from last time",
  "autoContinue": true
}

This is useful when:

• You don't know or care about the specific session ID
• You want to pick up exactly where you left off
• You're iterating on the last task

Note: autoContinue takes precedence over sessionId. When autoContinue is true, sessionId is ignored.

Prompt Files (promptFile)

For long prompts (e.g., detailed image generation descriptions), save the prompt to a file and reference it:

# Create a prompt file
cat > /tmp/image-prompt.txt << 'EOF'
Generate a mobile onboarding screen for an Islamic daily reflection app.
Use earthy tones, Islamic geometric patterns, and elegant Arabic calligraphy.
The screen should have:
- A large crescent moon and star icon at the top
- The app name "DeenScrolling" in elegant serif font
- A subtle geometric pattern background in deep teal (#0D4D4D)
- Two call-to-action buttons: "Get Started" and "Learn More"
- Soft ambient lighting from the bottom
EOF

Then reference it in the MCP call:

{
  "promptFile": "/tmp/image-prompt.txt",
  "workFolder": "/Users/me/projects/myapp"
}

Customizing the Tool Description

The antigravity_code tool description is loaded dynamically from a markdown file. This allows you to customize how the tool appears to your MCP client (Claude Desktop, OpenClaw, etc.).

How it works

1. Default: The server looks for description.md in the project root
2. Custom: Set AGY_MCP_DESCRIPTION_PATH to point to your own description file

Custom description file example

Create my-description.md:

# My Custom Antigravity Agent

Specialized for mobile app development with Flutter and Dart.

### Expertise
- Flutter UI/UX design and implementation
- Dart code generation and refactoring
- Image generation for app assets and mockups
- State management with Riverpod

### Workflow
1. Always generate test files alongside implementation
2. Follow the project's existing architecture patterns
3. Use relative paths when workFolder is set

Usage

# Set custom description via env var
AGY_MCP_DESCRIPTION_PATH=/path/to/my-description.md agy-mcp

# Or in MCP config
{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["-y", "agy-mcp@latest"],
      "transport": "stdio",
      "env": {
        "AGY_MCP_DESCRIPTION_PATH": "/path/to/my-description.md"
      }
    }
  }
}

The description file is read once at server startup. Restart the server after editing.

Environment Variables

Variable	Description
AGY_CLI_PATH	Absolute path to the agy binary (skip auto-discovery)
AGY_CLI_NAME	Custom binary name or path
AGY_MCP_DEBUG	Set to true for verbose stderr logging
AGY_MCP_TIMEOUT_MS	Command timeout in milliseconds (default: 600000 = 10min)
AGY_MCP_SESSION_FILE	Custom session mapping file path
AGY_MCP_DESCRIPTION_PATH	Custom tool description markdown file path

Acknowledgements

This project was directly inspired by claude-code-mcp by Peter Steinberger. I saw the idea of wrapping a CLI coding agent as an MCP server and thought: "That's brilliant — I want the same thing for Antigravity/Gemini."

So agy-mcp is not a competitor. It's a sibling project that applies the same pattern to a different AI provider. Same architecture, same goals, different backend.

Thank you, Peter — for proving this pattern works and making the MCP ecosystem richer.

Using Both Together

Since both are MCP servers, you can wire them into the same client:

Tool	Best For
claude_code (via claude-code-mcp)	Architecture, deep refactoring, complex reasoning
antigravity_code (via agy-mcp)	Design, image generation, web search, quick iteration

Example workflow:

1. Ask claude_code to design the component architecture
2. Ask antigravity_code to generate the onboarding image assets
3. Ask claude_code to wire the assets into the Flutter code

Same orchestrator, two specialized agents. That's the power of MCP.

Development

git clone https://github.com/Walapalam/agy-mcp.git
cd agy-mcp
npm install
npm run dev    # Run with tsx (auto-reload)
npm run build  # Compile to dist/
npm test       # Run tests

License

MIT

Author

Raqeeb M. (@Walapalam)

Built with ❤️ at Kawn Labs

Credits: Inspired by claude-code-mcp — thank you Peter Steinberger for pioneering the CLI-to-MCP bridge pattern.