agy MCP Server
Allows AI agents to interact with Google Antigravity's agy CLI, enabling prompt execution, session management, conversation continuation, and task automation with file-writing capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agy MCP Server explain the authentication flow in the current project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agy MCP Server
Bridge between Claude and Google Antigravity's agy CLI — let Claude Code (or any MCP client) drive the Antigravity agent through tool calls.
graph LR
A[Claude Code] --> B[agy MCP Server]
B --> C[agy CLI]
C --> D[Antigravity / Gemini]
style A fill:#FF6B35
style B fill:#4A90E2
style C fill:#00D4AA
style D fill:#FFA500This project mirrors the architecture of codex-mcp-server but wraps agy instead of codex.
How it works
agy exposes a non-interactive print mode: agy -p "<prompt>" runs a single
prompt (the prompt is the value of -p) and prints the response to stdout.
This server spawns agy -p "<prompt>" with the prompt as an argument, always
closes stdin so agy never blocks waiting for input, and returns stdout as the
MCP tool result. (agy only reads the prompt from stdin when -p is empty; a
bare -p with no value errors with "flag needs an argument".)
Related MCP server: Antigravity MCP Server
Requirements
agyCLI v1.0.3+ on yourPATH(agy --version). It ships with Google Antigravity.You must be logged into Antigravity —
agyreuses the desktop app's credentials, so there is no API key to configure here.
Install
Prerequisite (all methods): the
agyCLI (v1.0.3+) must be installed and logged into Antigravity on the machine that runs the MCP server.
A) Via GitHub + npx (no manual clone)
claude mcp add agy-cli -- npx -y github:toonPt0473/agy-mcp-servernpx clones the repo and runs the prepare script (tsc) to build dist/ on
first install, then launches the server. Requires git and Node on PATH.
Updates: bump the repo; npx re-fetches on the next cold install (or clear the npx cache).
B) From a local clone
git clone https://github.com/toonPt0473/agy-mcp-server.git
cd agy-mcp-server
npm install # runs the build automatically via the `prepare` script
claude mcp add agy-cli -- node "$(pwd)/dist/index.js"C) Global binary (decoupled from the source folder)
npm install -g . # in the cloned repo; exposes the `agy-mcp-server` bin
claude mcp add agy-cli -- agy-mcp-serverThis repo also ships a project-scoped .mcp.json pointing at dist/index.js,
which Claude Code picks up automatically when run from the project directory.
Tools
Tool | Description |
| Run a prompt through |
| List the models available to agy ( |
| View active conversation sessions |
| Test server connection |
| Get |
| Show |
agy tool parameters
Parameter | Type | Default | Description |
| string | — (required) | The task/question. Passed as the value of |
| string | — | Model for this call ( |
| string | — | Multi-turn context. First turn = fresh conversation; later turns continue it. |
| boolean |
| Start a fresh conversation for this session. |
| string | — | Resume a specific agy conversation ( |
| boolean |
| Force |
| string[] | — | Extra workspace dirs ( |
| boolean |
|
|
| boolean |
| ⚠️ |
| string |
|
|
Examples
Use agy to explain the auth flow in this repo
Use the models tool to see which agy models are available
Use agy with model "Claude Opus 4.6 (Thinking)" to review this design
Use agy with sessionId "refactor" to analyze this module
Use agy with sessionId "refactor" to now implement the change # continues the same conversation
Use agy with skipPermissions true and addDirs ["./src"] to refactor and write filesSelecting a model
agy v1.0.5+ supports choosing a model. List what's available with the
models tool (runs agy models), then pass the exact name as the model
parameter of the agy tool — names contain spaces/parentheses and are passed
safely as a single argument, e.g. Claude Opus 4.6 (Thinking) or
Gemini 3.5 Flash (High).
Precedence: per-call model arg → AGY_MCP_DEFAULT_MODEL env → omitted (agy
uses its own default). An unknown model name is not rejected — agy falls back
to its default. Requires agy ≥ v1.0.5 (older versions have no --model flag).
Session model & limitations
agyprint mode does not emit a conversation ID, so multi-turn within asessionIdusesagy --continue(continue the most recent conversation).Because "most recent" is global to
agy, avoid interleaving multiple sessions or runningagymanually in the middle of a session — the continuation could attach to the wrong conversation. For precise resume, pass aconversationIdyou obtained from the Antigravity app.Without
skipPermissions: true, a prompt that makesagywant to use a tool may block untilprintTimeout, since approvals can't be given non-interactively. UseskipPermissionsfor agentic/file-writing tasks; leave it off for Q&A.
Environment variables
AGY_BIN— path to theagybinary (default:agyonPATH).AGY_MCP_DEFAULT_MODEL— default--modelwhen not set per-call (default: none → agy's own default).AGY_MCP_PRINT_TIMEOUT— default--print-timeoutwhen not set per-call (default5m).AGY_MCP_LOG_DIR— enable conversation logging into this directory (see below).AGY_MCP_LOG_FILE— enable conversation logging into this single file (overridesAGY_MCP_LOG_DIR).STRUCTURED_CONTENT_ENABLED— emitstructuredContentin results (1/true/yes/on). Off by default;_metais always included for Claude Code.
Conversation logging
Every agy tool call (the prompt Claude sent and the response agy returned)
can be appended to a Markdown transcript. Logging is off by default;
enable it by setting one of:
AGY_MCP_LOG_DIR=/path/to/dir→ one file per day:agy-conversations-YYYY-MM-DD.mdAGY_MCP_LOG_FILE=/path/to/file.md→ a single file (takes precedence)
Set it in the env block of your .mcp.json, e.g.:
{
"mcpServers": {
"agy-cli": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:toonPt0473/agy-mcp-server"],
"env": { "AGY_MCP_LOG_DIR": "/abs/path/to/project/.agy-logs" }
}
}
}Each entry records the timestamp, mode (fresh/continue/resume), sessionId,
conversationId, duration, flags (sandbox/skipPermissions/addDirs), and the full
prompt and response. Logging failures are reported to stderr but never break the
tool. Add the log directory to .gitignore if you don't want transcripts committed.
Development
npm install # install dependencies
npm run dev # run from source with tsx
npm run build # compile to dist/
npm test # run the test suite
npm run lint # eslint
npm run format # prettierLicense
ISC
Available Tools
5 toolsagyADestructive
Run a prompt through the Antigravity CLI (agy) in non-interactive print mode and return the response. Supports multi-turn continuation, extra workspace directories, sandbox, and auto-approval of tool permissions.
Inputs: prompt (required), sessionId, resetSession, conversationId, +5 more.
changelogARead-onlyIdempotent
Show the Antigravity CLI (agy) changelog and release notes
Inputs: no named parameters.
helpARead-onlyIdempotent
Get Antigravity CLI (agy) help information
Inputs: no named parameters.
listSessionsARead-onlyIdempotent
List all active conversation sessions with metadata
Inputs: no named parameters.
pingARead-onlyIdempotent
Test MCP server connection
Inputs: message.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a unique purpose: running prompts, showing changelog, providing help, listing sessions, and testing connection. No overlap.
Tool names use inconsistent conventions: most are lowercase (agy, changelog, help, ping) but one is camelCase (listSessions). No clear pattern.
Five tools is appropriate for a CLI wrapper MCP server, covering core interactions without unnecessary complexity.
Core functionality is covered (run prompts, get help, list sessions), but missing tools for session management (e.g., end session) or configuration (e.g., auto-approval settings) are minor gaps.
Maintenance
Related MCP Connectors
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables calling Google's Antigravity CLI (agy) headlessly through MCP, providing tools like agy_ask and agy_research for agents like Claude Code.265 PyPI21MIT
- FlicenseNot gradedqualityDmaintenanceEnables external agents like Gemini Spark to control Google Antigravity CLI (agy) via Model Context Protocol, supporting multimodal inputs and automatic session management.-
- AlicenseAqualityCmaintenanceEnables AI harnesses to delegate code analysis, modification, testing, and long-running tasks to the locally installed Antigravity CLI via stdio MCP, with job status tracking and conversation continuity.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables Codex users to delegate engineering, refactoring, auditing, and test execution tasks to Google Antigravity CLI as a persistent autonomous subagent, with tools for managing sessions and running prompts.1MIT