agy-mcp-server
Exposes Google's Antigravity CLI agent as MCP tools, allowing MCP hosts to start and resume persistent Antigravity conversations, send questions, override workspace/model/effort/mode per call, stream live progress, and manage live agent conversations.
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 run the test suite and fix any failures in this repo"
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
An MCP server that exposes Google's Antigravity CLI (agy) as tools, so
any MCP host — OpenCode, Claude Desktop, Cursor, the MCP Inspector, your own
agent — can talk to the Antigravity agent.
MCP host (OpenCode / Claude Desktop / ...)
│ stdio (JSON-RPC 2.0, MCP)
▼
agy-mcp-server ──▶ agy --input-format stream-json --output-format stream-json
│ │
│ ▼
│ Antigravity agent (Gemini 3.x)
│ + native tools (shell, files, browser, web search)
│ + MCP servers registered in agy
▼
persistent conversations, streamed progressCompanion project: agy-openai — the same
idea for the OpenAI Chat Completions format.
Features
Persistent conversations — one long-lived
agyprocess per conversation, so the agent remembers context across tool calls. Conversations survive process restarts (agy persists them on disk and they are resumed by id).Live progress — agent text deltas are streamed to the host as MCP progress notifications while the turn runs.
Workspace / model / effort / mode per call — override any of them on a single
agy_ask.Idle handling — unused agent processes are closed after
AGY_IDLE_TTL; memory stays resumable. Live conversations are capped byAGY_MAX_CONVERSATIONS(LRU).No build step — plain ESM JavaScript, Node ≥ 20.
Related MCP server: codex-agy-bridge
Tools
Tool | What it does |
| Ask the agent in the current persistent conversation. |
| Ask in a fresh conversation (becomes the new default; the old one stays resumable). |
| Continue a conversation by our id or an agy conversation UUID. |
| List live conversations (id, workspace, model, agy id, last use). |
| Close a conversation's agent process (still resumable). |
| Model ids agy supports (cached 5 min). |
| agy version, signed-in account, config, conversations. |
agy_ask example parameters:
{
"question": "Summarise the git history of this repo",
"workspace": "/root/ssd/Projects/agy-mcp-server",
"model": "gemini-3.8-flash-high",
"effort": "high",
"mode": "accept-edits",
"timeout": 600
}Install
From GitHub Packages
# one-time: tell npm where @technicalheist packages live
echo "@shivrajansingh:registry=https://npm.pkg.github.com" >> ~/.npmrc
# auth (a GitHub token with read:packages)
echo "//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> ~/.npmrc
npm install -g @shivrajansingh/agy-mcp-serverFrom source
git clone https://github.com/shivrajansingh/agy-mcp-server.git
cd agy-mcp-server
npm installConfigure
Copy .env.example to .env (next to package.json) or export the variables.
Environment wins over the file. Highlights:
Variable | Default | Meaning |
|
| agy executable |
| server cwd | default workspace |
| agy defaults | conversation defaults |
|
| permission allow rules |
| (empty) | permission deny rules |
|
|
|
|
| per-turn timeout (seconds) |
|
| how long a second ask waits on a busy conversation |
|
| hibernation TTL for idle conversations |
|
| max live agent processes |
|
| stream deltas as MCP progress notifications |
Register with a host
OpenCode
~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"agy": {
"type": "local",
"command": ["agy-mcp-server"],
"environment": {
"AGY_WORKSPACE": "/root/ssd/Projects"
}
}
}
}Or with an explicit path:
"command": ["node", "/root/ssd/Projects/agy-mcp-server/bin/agy-mcp-server.js"]Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"agy": {
"command": "agy-mcp-server",
"env": { "AGY_WORKSPACE": "/home/me/projects" }
}
}
}MCP Inspector
npx @modelcontextprotocol/inspector \
node /path/to/agy-mcp-server/bin/agy-mcp-server.jsRequirements
Node.js ≥ 20
agyinstalled and logged in (agy --version,agy models). The server is verified against agy 1.5.5; afteragy update, re-check the stream-json contract withagyq doctor(the wrapper the protocol was reverse-engineered from).
Notes and limits
One turn at a time per conversation. agy's stream-json loop is strictly sequential; a second concurrent
agy_askwaits up toAGY_BUSY_TIMEOUT. Useagy_ask_newfor parallel work.ask_useris not exposed. An MCP server cannot synchronously call a tool back into its host, so there is nobody to answer. The agent either works it out or reports that it needs input.The agent acts on the machine running this server. Its native tools (shell, files, browser) and agy-registered MCP servers execute here. Use
AGY_ALLOW/AGY_DENYto constrain it.Tool execution and model calls are billed by Google/Antigravity as usual; each turn is a full agent loop (seconds to tens of seconds).
stdout carries the MCP protocol; all logs go to stderr.
Development
npm install
npm run test:smoke # real agy round-trip
npm test # tool surface via in-memory client
AGY_TEST_LIVE=1 npm test # + a real agy_ask turnLicense
MIT © Technical Heist
Available Tools
7 toolsagy_askAsk the Antigravity agentA
Ask Google's Antigravity agent a question in the current persistent conversation. The agent keeps its memory across calls; it can use its native tools (shell, files, browser, web search) and any MCP servers registered in agy. Returns the agent's final answer.
Inputs: question (required), mode, model, effort, +3 more.
agy_ask_newAsk the Antigravity agent (new conversation)A
Same as agy_ask but starts a fresh conversation with no prior context. The previous default conversation stays alive and can be resumed with agy_resume.
Inputs: question (required), mode, model, effort, +2 more.
agy_conversationsList Antigravity conversationsA
List the live conversations managed by this MCP server: ids, workspace, model, agy conversation id, and last use.
Inputs: no named parameters.
agy_modelsList Antigravity modelsA
List the model ids the installed agy supports (cached 5 min).
Inputs: no named parameters.
agy_resumeResume an Antigravity conversationA
Continue a previous conversation by id. Accepts either a conversation id returned by agy_ask/agy_ask_new or an agy conversation UUID (as shown in agy_conversations / agy's history).
Inputs: question (required), conversation_id (required), mode, model, +3 more.
agy_statusAntigravity statusA
Report agy version, the signed-in account, configuration in effect, and the live conversations managed by this server.
Inputs: no named parameters.
agy_stopStop an Antigravity conversation processA
Close the agent process for a conversation to free memory. The conversation's memory stays on disk and can be resumed later with agy_resume. Defaults to the current default conversation.
Inputs: conversation_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
The core trio (agy_ask, agy_ask_new, agy_resume) is clearly delineated by the persistent-vs-fresh-vs-resume distinction, and agy_stop/agy_models are unmistakable. The only soft overlap is agy_status vs agy_conversations, since status also reports live conversations, but the descriptions make the difference (diagnostics vs enumeration) reasonably clear.
All names share a uniform `agy_` prefix and snake_case, which makes the set highly predictable. The only minor wrinkle is the mixed verb/noun style (agy_ask/agy_resume/agy_stop vs agy_models/agy_conversations/agy_status), though that maps naturally to action vs listing tools.
Seven tools is a tight, well-scoped surface for a conversation-lifecycle wrapper around a single external agent. Each tool covers a distinct lifecycle step (start, fresh start, resume, list, stop, introspect models, introspect status) with no filler.
The conversation lifecycle is essentially covered: create, create-fresh, resume, list, stop, plus introspection of models and status. Gaps are minor but real: there is no way to pass a model selection into agy_ask despite agy_models existing, and no way to inspect or delete conversation history/messages.
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Orbit is an MCP server that gives your AI agents a 4000+ tools, a shared memory brain and a live dashboard OS. Every agent reads active decisions, logs outputs to a searchable vault, and reports status in real time. 2-minute setup via MCP; works across Claude, ChatGPT, Codex, Cursor, Gemini, and Manus. Finally Agents work, agents that grow your business and bring you customers. https://orbitagents.xyz
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
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 PyPI20MIT
- AlicenseBqualityBmaintenanceAn MCP bridge that lets Codex delegate long-running agent work to the Antigravity CLI, providing observable and resumable tool-based execution with project scoping.1479 PyPI17MIT
- AlicenseAqualityDmaintenanceWraps Google's Antigravity CLI as MCP tools for Claude, enabling cost-disciplined multi-model execution with background jobs and fan-out research/review pipelines.13MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible coding agents to run the local Antigravity CLI as a coding agent, manage conversation context and common options, and inspect usage, quota, models, version, help, and read-only slash commands.26 npmMIT