Skip to main content
Glama

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 progress

Companion project: agy-openai — the same idea for the OpenAI Chat Completions format.

Features

  • Persistent conversations — one long-lived agy process 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 by AGY_MAX_CONVERSATIONS (LRU).

  • No build step — plain ESM JavaScript, Node ≥ 20.

Related MCP server: codex-agy-bridge

Tools

Tool

What it does

agy_ask

Ask the agent in the current persistent conversation.

agy_ask_new

Ask in a fresh conversation (becomes the new default; the old one stays resumable).

agy_resume

Continue a conversation by our id or an agy conversation UUID.

agy_conversations

List live conversations (id, workspace, model, agy id, last use).

agy_stop

Close a conversation's agent process (still resumable).

agy_models

Model ids agy supports (cached 5 min).

agy_status

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-server

From source

git clone https://github.com/shivrajansingh/agy-mcp-server.git
cd agy-mcp-server
npm install

Configure

Copy .env.example to .env (next to package.json) or export the variables. Environment wins over the file. Highlights:

Variable

Default

Meaning

AGY_BIN

agy then ~/.local/bin/agy

agy executable

AGY_WORKSPACE

server cwd

default workspace

AGY_MODEL / AGY_EFFORT / AGY_MODE

agy defaults

conversation defaults

AGY_ALLOW

command(*),mcp(*)

permission allow rules

AGY_DENY

(empty)

permission deny rules

AGY_SKIP_PERMISSIONS

0

1 = --dangerously-skip-permissions

AGY_ASK_TIMEOUT

900

per-turn timeout (seconds)

AGY_BUSY_TIMEOUT

120

how long a second ask waits on a busy conversation

AGY_IDLE_TTL

1800

hibernation TTL for idle conversations

AGY_MAX_CONVERSATIONS

8

max live agent processes

AGY_MCP_PROGRESS

1

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.js

Requirements

  • Node.js ≥ 20

  • agy installed and logged in (agy --version, agy models). The server is verified against agy 1.5.5; after agy update, re-check the stream-json contract with agyq 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_ask waits up to AGY_BUSY_TIMEOUT. Use agy_ask_new for parallel work.

  • ask_user is 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_DENY to 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 turn

License

MIT © Technical Heist

Available Tools

7 tools
agy_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

    A3.8/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      MIT