antigravity-mcp
This MCP server lets an orchestrating AI delegate background coding/analysis/research jobs to Antigravity's local agent engine and keep working while they run.
Dispatch background agents –
dispatch_gemini_agentstarts a job and immediately returns ajob_id, never blocking the caller.Check job status and output –
check_agent_jobreturns status, elapsed time, progress log, and final output.List active/recent jobs –
list_active_jobsshows in-flight and recent job history, persisted across sessions.Cancel running jobs –
cancel_agent_jobcooperatively stops a job.Synchronous multi-file code search –
gemini_code_searchscans many files at once and answers architectural/code questions synchronously.Discover available models –
list_available_modelsreturns the live model catalog from the connected Antigravity IDE session.Model selection flexibility – pass exact labels or loose descriptions (e.g. "flash", "opus") with strict matching.
Works without an API key when the Antigravity IDE is open; falls back to the Gemini REST API if the IDE isn't running and a key is set.
Configurable concurrency, timeouts, and state location via environment variables.
Uses Google's Gemini REST API as a fallback execution backend when the local Antigravity language server is unavailable and a GEMINI_API_KEY or GOOGLE_API_KEY is configured, allowing background agent jobs and code-search queries to run against Gemini models hosted by Google.
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., "@antigravity-mcp dispatch a background job to scan the repo for unused exports"
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.
antigravity-mcp
Delegate background subagent jobs to the Antigravity IDE's local agent engine — from Claude Code, Codex, Cursor, or any other MCP client.
If you have the Antigravity IDE open and signed in, you already have a local agent engine with a catalog of frontier models sitting idle. This is an MCP server that exposes that engine as a handful of tools, so the model you actually drive your work with can hand jobs off to it and keep going.
Your orchestrator stays the architect. The subagents do the legwork.
┌─────────────────────────────────────────────────┐
│ Your MCP client │
│ (Claude Code · Codex · Cursor · anything else) │
│ plans the work, reviews every result │
└───────────────────────┬─────────────────────────┘
│ MCP · JSON-RPC 2.0 over stdio
▼
┌─────────────────────────────────────────────────┐
│ antigravity-mcp │
│ returns a job_id immediately, never blocks │
│ bounded worker pool · job history on disk │
└───────────────────────┬─────────────────────────┘
│ tried in order
┌─────────────────┼─────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Antigravity │ │ Gemini REST │ │ Explicit │
│ language │ │ API │ │ failure │
│ server │ │ │ │ │
│ no API key │ │ needs a key │ │ never faked │
└───────────────┘ └───────────────┘ └───────────────┘Why
Orchestrating models are expensive and serial. Plenty of real work isn't worth their attention: scanning forty files to answer one architectural question, generating the fifth round of near-identical fixtures, or reading a dependency tree you already understand. Hand those to a fast local worker, keep planning while it runs, and collect the result when you need it.
Because jobs run on the IDE's own authenticated session, no API key is needed when the IDE is open.
Related MCP server: sub-antigravity
Install
pip install git+https://github.com/Kio-pon/antigravity-mcp.gitOr clone it — there are no dependencies, so a checkout runs as-is on a bare interpreter:
git clone https://github.com/Kio-pon/antigravity-mcp.gitRegister with your MCP client
claude mcp add antigravity-agents -- antigravity-mcpFrom a clone instead of an install:
claude mcp add antigravity-agents -- python3 /path/to/antigravity-mcp/src/antigravity_mcp/__main__.pyAdd to ~/.codex/config.toml:
[mcp_servers.antigravity-agents]
command = "antigravity-mcp"{
"mcpServers": {
"antigravity-agents": {
"command": "antigravity-mcp",
"env": {
"ANTIGRAVITY_MAX_CONCURRENT_JOBS": "3"
}
}
}
}Ready-made config files live in examples/.
Verify it is wired up by asking your client to call list_available_models. With the IDE open you should get back the live model catalog.
Tools
Tool | Arguments | What it does |
|
| Starts a background job. Returns a |
|
| Status, elapsed time, progress log, and output. |
|
| Recent and in-flight jobs. |
|
| Cooperatively stops a running job. |
|
| Scans many files at once and answers synchronously. |
| — | The live model catalog from your IDE session. |
Picking a model
The catalog is whatever your Antigravity account currently has, and it changes as models ship — so nothing is hardcoded. Call list_available_models to see it, then pass either an exact label or a loose description:
"Gemini 3.8 Flash (High)" exact label
"gemini 3.7 flash medium" version + family + effort tier
"flash" best available flash — highest effort, newest version
"opus" best available OpusMatching is token-based and strict about what you do specify: every word and version number you give has to appear in the model's label. "gemini-3.5-flash" will not quietly resolve to a 3.7 model just because both are flash — it raises and lists what actually exists. Leave a dimension out and it is a wildcard, resolved to the highest effort tier and newest version that fits.
How a session usually goes
1. dispatch_gemini_agent → job_id, returned instantly
2. …carry on with your own work…
3. check_agent_job → output when it's ready
4. review before applying anything to filesStep 4 is the point of the whole design. A subagent's output is a proposal, not a commit.
Execution backends
Two backends, tried in order:
Local Antigravity language server — the default. Connects over loopback HTTPS and reuses the IDE's signed-in session. No API key.
Gemini REST API — used when the IDE is not running and
GEMINI_API_KEYorGOOGLE_API_KEYis set.
If neither is reachable the job fails with an error saying so. There is deliberately no further tier that returns a stand-in result: a plausible answer no model actually produced is worse than an error, because nothing downstream can tell the two apart.
Configuration
All optional.
Variable | Default | Purpose |
|
| Jobs running at once. Every job drives a live session on the same language server process, so this is a real resource ceiling, not a formality. Extra jobs queue. |
|
| Seconds before a job is abandoned. Completion is detected, not waited out — a short single-shot answer returns in seconds — so a generous ceiling only bounds a genuinely stuck agent. |
|
| Tool calls handled in parallel. |
| platform state dir | Where job history is kept. |
| unset | Skip the local backend entirely. |
|
| Server log level on stderr. |
| unset | Enables the REST fallback. |
Job history is written to $XDG_STATE_HOME/antigravity-mcp/jobs.json on Linux, ~/Library/Application Support/antigravity-mcp/ on macOS, and %LOCALAPPDATA%\antigravity-mcp\ on Windows — never into the install tree. It survives across sessions, which is what makes a job_id from yesterday still mean something today.
The optional skill
skills/antigravity-agent/ is a Claude Code skill that teaches the orchestrator when delegating is worth it, so you don't have to say it every time. Install it with:
cp -r skills/antigravity-agent ~/.claude/skills/Protocol support
The server implements the current 2026-07-28 specification and the
handshake-based revisions before it, deciding per request which one a client is
speaking. Modern clients declare their version in each request's _meta; legacy
clients open with initialize. Both work against the same process with no
configuration, and server/discover reports every version on offer.
Because stdio has no HTTP status codes to drive fallback, server/discover is
also how a client tells a modern server from a legacy one — so it is answered
before anything else.
Compatibility
The local backend speaks private IDE IPC —StartCascade, SendUserCascadeMessage, GetUserStatus, GetCascadeTrajectory over loopback Connect-RPC. These are internal endpoints with no cross-version stability guarantee. An IDE update can change them.
Status | |
MCP specification | 2026-07-28 (current), plus 2025-06-18, 2025-03-26, 2024-11-05 |
Antigravity IDE | Verified against v1.107.0 ( |
Linux | Verified — process discovery via |
macOS | Implemented via |
Windows | Implemented via |
Python | 3.9+ |
Running it on macOS or Windows? A quick issue saying whether discovery found your language server would be genuinely useful — that's the one part that cannot be tested without the hardware.
Development
git clone https://github.com/Kio-pon/antigravity-mcp.git
cd antigravity-mcp
pip install -e ".[dev]"
pytestThe default suite is hermetic — no IDE, no network, no API key — driving the real request path with a stub executor in place of a language server. To also run the live round-trip against a real one, open the IDE and set ANTIGRAVITY_LIVE_TESTS=1.
See CONTRIBUTING.md.
License
MIT.
Not affiliated with, endorsed by, or supported by Google or the Antigravity IDE team.
Available Tools
6 toolscancel_agent_jobB
Cancel a running background subagent job.
Inputs: job_id (required).
check_agent_jobB
Check the status, logs, duration, and output of a dispatched agent job.
Inputs: job_id (required).
dispatch_gemini_agentA
Dispatch a coding, analysis, or research task to a background Antigravity subagent. Returns immediately with a job_id so the orchestrator is never blocked.
Inputs: task (required), model, context_files, system_instruction.
gemini_code_searchB
Use a large-context model to scan multiple repository files at once and answer architectural or code questions about them. Runs synchronously and returns the answer.
Inputs: query (required), context_files (required).
list_active_jobsC
List active, pending, completed, cancelled, or failed subagent jobs.
Inputs: limit.
list_available_modelsA
List the live models currently available from the connected Antigravity IDE session. Call this before dispatch_gemini_agent when you do not already know an exact, currently-live model name.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools are clearly distinct: dispatch/check/list/cancel form a clean job-management set, and list_available_models is unique. The main soft spot is gemini_code_search vs dispatch_gemini_agent, since both invoke Gemini to reason over code, though the sync-scan vs async-agent distinction in the descriptions mostly resolves it.
Five of six names follow a clean verb_noun pattern (dispatch_gemini_agent, list_available_models, check_agent_job, list_active_jobs, cancel_agent_job). gemini_code_search breaks the convention by leading with the noun/qualifier rather than a verb, a minor deviation in an otherwise consistent set.
Six tools is well-scoped for an orchestration server covering sync code Q&A, async dispatch, model discovery, and job lifecycle management. Each tool earns its place with no redundant or filler operations.
The subagent job lifecycle is well covered (dispatch, check status/logs/output, list, cancel), plus code search and model listing. Minor gaps remain, such as no explicit job-resume/retry or log-streaming tool, but agents can work around these.
Maintenance
Related MCP Connectors
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceIntegrates Google Antigravity's agy agent into MCP, enabling asynchronous delegation of complex tasks like code analysis and file management with job polling.142 npm3MIT
- 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
- AlicenseAqualityBmaintenanceLets an MCP client hand coding tasks, second-opinion reviews, and image-asset generation to the official OpenAI CLI agent running locally, returning final messages, session IDs, and saved files. Jobs run sandboxed with prompts over stdin, work asynchronously with polling, and expose a live model catalog without needing an API key.5MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to delegate background subagent jobs to an IDE's local agent engine, queue and monitor them, and retrieve results while the orchestrator continues working.7MIT