agy-mcp
One-line summary: agy-mcp exposes Google's Antigravity CLI (agy) as 11 typed MCP tools, letting any MCP client delegate prompts to it, run/poll background jobs, manage sessions, and install collaboration skills — all behind a safety/redaction policy.
Synchronous calls —
agyrunsagy --printonce and returns assistant text plus a stableBridgeResponseenvelope (cd, mode, sandbox, model, session, timeout, worktree,allow_write,extra_env,output_protocol).Conversation resume —
agy_continuecontinues an existing session via a requiredSESSION_ID.Background jobs —
agy_startlaunches long-running work and immediately returns ajob_idto poll.Job monitoring —
agy_status(status/exit code/timestamps),agy_read(streamed event log, withsinceoffset and raw/claude/codex translation).Job output retrieval —
agy_resultfetches finished output (result_text), optionally including events; omitjob_idfor the latest finished job.Job control —
agy_cancelsignals a running job's process group to stop (cross-platform).Session history —
agy_sessionslists recent jobs newest-first with alimit.Environment diagnostics —
agy_doctorprobes environment, auth, and capabilities without leaking secrets; supportsforce_refresh.Skill installation —
agy_install_skillinstalls the collaboration SKILL bundle for Claude, Codex, and/or Antigravity at user or project scope, withforceto overwrite.Retention cleanup —
agy_purgedeletes session-store jobs older thandays(rejectsdays <= 0).Modes for intent — each run picks a mode:
ask,plan,prototype,review,execute,browser, orlong(writes inexecuterequire explicitallow_write=True, defaulting to an isolated worktree).Safety guarantees — paths, PEM/JWT/AKID/Bearer tokens and other secrets are redacted in all errors, logs, and responses; destructive prompts are refused.
Provides tools for interacting with Google's Antigravity CLI, enabling AI agents to execute prompts, run sandbox sessions, manage long-running jobs, and inspect environment 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 review this pull request diff for security issues"
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
把 Google Antigravity CLI(
agy)包装成 11 个 typed MCP 工具, 任何 MCP 客户端(Claude Code / OpenAI Codex / Cursor / Cline / Continue …)都能直接调用。配套可选 Skill bundle,让支持 skill 的 平台学会何时调、用哪个 mode。
快速开始
# 1. 装 uv(已有可跳过)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. 装 agy-mcp(从 PyPI)
uv tool install agy-mcp
# 3. 注册 MCP server(以 Claude Code 为例;其它客户端见折叠区)
claude mcp add agy -s user --transport stdio -- agymcp
# 4. (可选)装 SKILL,让 Claude / Codex / Antigravity 学会何时调
agy-install-skill --target all
# 5. 验证(不调真实 agy API)
agy-doctor请帮我把 agy-mcp 这个开源 MCP 安装好。具体目标:
1. 用 uv tool 装本仓库的 console scripts(agymcp / agy-bridge /
agy-doctor / agy-install-skill)。如果本机没有 uv,先用
`curl -LsSf https://astral.sh/uv/install.sh | sh` 装好。
2. 把 agy MCP server 注册到我当前正在使用的 agent 平台:
- 如果你是 Claude Code,执行:
`claude mcp add agy -s user --transport stdio -- agymcp`
并用 `claude mcp list` 确认 `agy: ✓ Connected`。
- 如果你是 OpenAI Codex CLI,向 `~/.codex/config.toml` 追加:
```toml
[mcp_servers.agy]
command = "agymcp"
args = []
```
并重启 Codex 会话让其生效。
3. 装协作 SKILL(让本平台知道何时调用 agy):直接调用刚才暴露的
`agy_install_skill` MCP 工具,参数 `targets=["all"], scope="user"`。
它会写到 `~/.claude/skills/`、`~/.agents/skills/`、`~/.agy/skills/`
三处。装完后告诉我重启窗口让 SKILL 生效。
4. 验证:调用 `agy_doctor` MCP 工具,把返回的 JSON 完整贴给我看;
预期 `healthy=true`,主要 check 全部 `ok=true`。如果 `auth` 这项
显示未登录,告诉我手动跑一次 `agy --version` 触发 OAuth 流程,
然后再调一次 `agy_doctor`。
5. 安装来源默认走 PyPI:`uv tool install agy-mcp`。如果我让你装某个
未发布分支或本地 clone,再切到 `git+https://github.com/Boulea7/agy-mcp.git`
或本地 `--from <项目本地绝对路径>`。
约束:
- 不要 push 任何东西、不要改我的 .gitconfig。
- 在没有我确认前不要调真实的 `agy` 模型(只能跑 doctor / dry-run)。
- 任何写入操作(包括上面这些)做之前先简短说一下要做什么,等我点头
再执行;如果你的当前权限模式允许 acceptEdits,就直接执行。
每完成一步给我一行汇报,全部完成后给出一份 4 行总结:装在哪、11 个
MCP 工具是否齐、SKILL 落地路径、剩余可选项。OpenAI Codex CLI:向
~/.codex/config.toml追加:[mcp_servers.agy] command = "agymcp" args = []重启 Codex 会话生效。
Cursor / Cline / Continue / 其它 MCP 客户端:在客户端的 MCP server 配置里加一条 name=
agy、command=agymcp、transport=stdio 即可。具体语法各家不同,参考各自文档。
完整安装与故障排查 → docs/installation.md。
Related MCP server: Antigravity MCP Server
它是什么
把 Google 新发布的 Antigravity CLI(agy)包装成可被任意 MCP 客户端
调用的协作 agent backend。两条等价路径:
MCP server:
agymcp经 FastMCP stdio 暴露 11 个 typed JSON 工具, pydantic envelope 稳定可解析。任何 MCP 客户端皆可。Skill bundles:装到
~/.claude/skills/、~/.agents/skills/、~/.agy/skills/,教 agent 何时调 agy、用哪个 mode、注意哪些安全 规则。仅对 Claude Code / OpenAI Codex / Antigravity 三家有效。共享 backend:两条路径都走同一
bridge.py→ adapter → safety policy → worktree,行为一致。
除
agy_doctor与--dry-run外,agy/agy_start会启动真实agy --print,可能消耗 Antigravity 请求额度。本项目只包装、路由、 隔离、审计,不重新实现agyAPI。
11 个 MCP 工具
工具 | 用途 |
| 同步一次性调用(PROMPT / cd / sandbox / SESSION_ID + |
| 续 |
| 后台启动长任务,立即返回 |
| 查 job 状态:running / completed / failed / cancelled / upstream_error; |
| 读 job 事件流(raw / claude / codex 三协议); |
| 取已完成 job 的结果;不传 |
| 跨平台 process group 终止; |
| 列最近 session |
| 环境 + 鉴权 + capability 探测(不泄漏 secrets) |
| 把 SKILL bundle 装到 Claude / Codex / Antigravity 目录 |
| 清理本机 session-store 目录(refuse |
何时调用 / 何时不调用
情景 | 建议路径 |
上下文里能直接答的 Q&A | 不调,自己答 |
Bug 假设的第二意见 |
|
给 review 用的 diff |
|
应用 reviewed diff |
|
数小时大重构 |
|
需要 Anthropic / OpenAI 对话状态 | 不调 —— |
安全底线
所有错误 / 日志 / 响应字段先过
SafetyPolicy.redact:/Users/<u>/→~/,PEM / JWT / AKID / Bearer 全脱敏;mode=execute写入必须显式allow_write=True;destructive prompt 即使置位仍拒;execute模式下读 / 提及~/.ssh、~/.aws/credentials、浏览器 cookie、OS keychain 都拒;mode=execute + allow_write默认worktree=True(可经~/.config/agy-mcp/config.toml或AGY_MCP_WORKTREE_DEFAULT=0关闭);不写任何文件到
~/.gemini/(Antigravity CLI 自有状态目录);user-scope antigravity skill 落在~/.agy/skills/。
完整威胁模型与「不防御」清单 → docs/security.md。
项目协议片段
直接复制到项目根的 CLAUDE.md / AGENTS.md:
prompts/CLAUDE.md— Claude Code 协作协议prompts/AGENTS.md— OpenAI Codex 协作协议prompts/antigravity-system.md—agy端 system prompt 建议
文档目录
文件 | 内容 |
安装 + Claude Code / Codex 注册 + SKILL + 验证 | |
模块图(caller / MCP server / bridge / supervisor / adapter / safety) | |
Hybrid backend:stdout + klog + transcript.jsonl + 协议翻译器 | |
English README | |
繁體中文 README | |
日本語 README | |
威胁模型、防护清单、明确不防御项 | |
| |
7 个典型场景 | |
Stream-json passthrough vs Hybrid backend 两种 wrapper 模式对比 | |
PyPI trusted publishing + GitHub Release 发布手册(一次性设置 + 常规流程) | |
版本变更记录(Keep a Changelog) |
开发
uv sync
uv run pytest # 全量测试
uv run agymcp # 启动 MCP stdio server(人工测试用)
uv run agy-bridge --cd . --PROMPT "Hello" --mode ask --dry-run --debug
uv run agy-doctor # 环境与鉴权探测License
MIT.
Available Tools
11 toolsagyA
Run agy --print synchronously and return the assistant text + metadata. Compatible drop-in for the legacy gemini tool: same PROMPT / cd / sandbox / SESSION_ID / return_all_messages / model fields, with new mode / timeout / allow_write / worktree / backend / output_protocol options.
Inputs: PROMPT (required), cd, mode, debug, +11 more. Returns: Stable result envelope returned by the bridge CLI and MCP tools.
agy_cancelA
Signal a running job to stop by full job_id or unique prefix. Returns success=True, signalled=True if the worker was alive, signalled=False if it was unknown / already finished.
Inputs: job_id (required). Returns: Envelope returned by ``agy_cancel``.
agy_continueA
Continue an existing agy session. Identical to agy except SESSION_ID is required and the underlying adapter resumes the Antigravity conversation.
Inputs: PROMPT (required), SESSION_ID (required), cd, mode, +11 more. Returns: Stable result envelope returned by the bridge CLI and MCP tools.
agy_doctorA
Run capability + auth + session-store probes. Returns a structured report (no secrets) suitable for surfacing to a user via MCP. Pass force_refresh=true to drop the cached binary probe (use after upgrading the underlying agy / gemini CLI without restarting the MCP server).
Inputs: force_refresh. Returns: Envelope returned by ``agy_doctor``. ``report`` is a generic dict — DoctorRepor…
agy_install_skillA
Install the agy-mcp collaboration skill bundle into one or more agent platforms. targets may include 'claude', 'codex', 'antigravity', or 'all' (default expands to all three). User scope writes to ~/.claude/skills/, ~/.agents/skills/, and ~/.agy/skills/ respectively; project scope writes to .claude/skills/, .agents/skills/, and .antigravity/skills/ under the supplied project_root. Antigravity's wrapper-owned ~/.agy/ is used in user scope because the standing rule 'do not write under ~/.gemini/' rules out the Antigravity CLI's own state directory. force=False (the default) skips files whose on-disk body already matches; force=True rewrites every file unconditionally.
Inputs: force, scope, targets, project_root. Returns: Envelope returned by ``agy_install_skill``.
agy_purgeA
Delete session-store job directories whose mtime is older than days. Returns the removed job ids and a coarse count of remaining jobs. days must be a positive integer <= 3650; zero or negative values are rejected to avoid an accidental wipe via off-by-one config.
Inputs: days. Returns: Envelope returned by ``agy_purge``. ``removed`` carries the redacted job ids th…
agy_readB
Read events from a job's event log. since is the 0-based offset; translate may be 'raw', 'claude', or 'codex' to wire-format the events (default returns canonical events as dicts). job_id may be a full id or unique prefix.
Inputs: job_id (required), since, translate. Returns: Envelope returned by ``agy_read``. ``events`` is a list of generic dicts becaus…
agy_resultA
Return the captured output for a finished background job. Pass job_id (full id or unique prefix) to select a job, or omit it to use the latest finished job from agy_sessions. Set include_events=true to also return stored events; otherwise use agy_read for the full event log.
Inputs: since, job_id, include_events. Returns: Envelope returned by ``agy_result``.
agy_sessionsA
List recent jobs, newest first. limit defaults to 50; pass 0 for the full list.
Inputs: limit. Returns: Envelope returned by ``agy_sessions``.
agy_startA
Start an agy session in the background. Returns an envelope with status='running' and a job_id you can poll via agy_status / agy_read / agy_cancel.
Inputs: PROMPT (required), cd, mode, debug, +10 more. Returns: Stable result envelope returned by the bridge CLI and MCP tools.
agy_statusB
Return the JobRecord (status, exit code, error, timestamps) for a job_id or unique job-id prefix.
Inputs: job_id (required). Returns: Envelope returned by ``agy_status``.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct role: synchronous run vs background start vs continue, and job inspection is split into status, result, read, and sessions with descriptions that explain the boundaries. The overlap around job state/output is minimal and resolvable from the descriptions.
Names are consistently snake_case with an agy_ prefix, except for the main tool named simply 'agy' as a legacy drop-in. The verb/noun mix (start, read, cancel vs status, result, sessions) is readable but not a single uniform pattern.
Eleven tools is well-scoped for an MCP wrapper that manages background jobs, synchronous runs, sessions, diagnostics, and skill installation. Each tool appears to earn its place without obvious redundancy.
The surface covers the core job lifecycle: start, run, continue, status, read, result, cancel, list, and purge, plus diagnostics and skill installation. Minor gaps exist, such as no explicit single-job deletion or skill uninstall/update operation, but agents can work around them.
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
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
- 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
- AlicenseAqualityDmaintenanceBridges Google Antigravity CLI with MCP clients, enabling 13 specialized tools for AI-assisted coding, automation, and security audits.13MIT
- AlicenseAqualityCmaintenanceLets MCP clients such as Claude Code, Claude Desktop, Cursor, or Codex hand tasks to the Antigravity CLI (agy) so the work runs on the user's Antigravity plan instead of the client's. Exposes tools for delegated coding tasks and reviews, web search with sources, image/PDF analysis, shell command generation or execution, brainstorming, and model/quota checks.7MIT