agy-mcp

Status: pre-release. Interfaces, tool schemas and on-disk job records may change without a deprecation cycle.

agy-mcp is an MCP (Model Context Protocol) stdio server that orchestrates autonomous coding jobs run by the Google Antigravity CLI (agy). For each job it creates an isolated git worktree and branch, launches agy in its own process group with a sanitized environment, supervises it (wall-clock deadline, periodic security audit, COMMIT_MSG watcher), runs an optional verification command, and returns a standard result envelope through ten MCP tools. The wrapper never merges or pushes: landing a change is your decision.

Requirements

• Linux (tested), macOS (untested), Windows via WSL (untested). The installer is a bash script and the server uses POSIX process control. See doc/developing/platform-support.md for the per-platform audit; native Windows is not supported.

• Python 3.12 or newer. The installer refuses anything older.

• git on PATH. Every job is a git worktree and commits are git commits.

• The agy CLI installed and signed in, on PATH or at ~/.local/bin/agy. AGY_MCP_AGY_BINARY overrides the location. The installer never runs agy and never checks your login.

Related MCP server: agy-worker-mcp

Install

Clone the repository and run the installer from the checkout:

git clone https://github.com/harshp2008/agy-mcp.git
cd agy-mcp
./installer/install.sh --dry-run   # optional: print every write, change nothing
./installer/install.sh             # default client: generic

Run this from a normal terminal, not from inside a dsh session: the installer refuses to change dsh registration while dsh is running the command. The --help output is the authority for flags; the current set is:

Environment equivalents: AGY_MCP_CLIENT, AGY_MCP_DRY_RUN=1, AGY_MCP_SRC, AGY_MCP_EDITABLE=1, AGY_MCP_UPGRADE=1, AGY_MCP_PYTHON, AGY_MCP_PIP_ARGS, AGY_MCP_NO_RESTART=1, AGY_MCP_AGY_BINARY.

The installer creates its own virtualenv under ${CONF_DIR:-$HOME/.config/ai-stack}/agymcp and installs this checkout into it. It writes:

• ${CONF_DIR:-$HOME/.config/ai-stack}/agymcp/: venv/, run.sh (mode 755), env (mode 600), mcp-client-config.json, orchestrator-guidance.md;

• ${XDG_CONFIG_HOME:-$HOME/.config}/agy-mcp/config.toml, only when the file does not exist yet, with safe first-install defaults;

• the state directory ${XDG_STATE_HOME:-$HOME/.local/state}/agy-mcp (mode 0700);

• with --client dsh only: a marker block in ~/.dsh/profiles/web/cordis.patch.yml and a guidance block in ~/.dsh/AGENTS.md, both after a .bak backup.

A rerun skips pip when the venv already imports agy_mcp; use --upgrade to reinstall. --uninstall removes only the generated files and marker blocks and keeps your config, state directory and .bak backups.

Register with your MCP client

The default (generic) install writes and prints this mcpServers snippet:

{
  "mcpServers": {
    "agy": {
      "command": "/home/user/.config/ai-stack/agymcp/run.sh",
      "args": [],
      "env": {}
    }
  }
}

On your machine the command is the absolute path the installer wrote; use that path. Paste the object into your client's mcpServers map and paste orchestrator-guidance.md into its instruction file. Set the client's tool-call timeout to at least 360000 ms: agy_wait may block for up to 300 s and the client needs headroom.

Quick start

1. Run agy once yourself, sign in, and finish any first-run prompt. This is the one deliberate human step; the wrapper cannot do it for you.

2. In your MCP client, call agy_usage (read-only) to see the masked account and remaining quota before starting a long job.

3. Start a job on a git repository with at least one commit. The repository must be inside your configured allowed_workdir_roots (the installer's default is [$HOME]), must not be $HOME itself, and must not track a .agents/ directory unless you set trust_agents_dir = true.

   {"repo_path": "~/code/widget", "title": "Add a retry helper",
    "prompt": "Add a bounded retry helper in src/widget/retry.py with tests.",
    "verify": "pytest -q"}

   agy_start returns as soon as the job is queued. The worktree lives under the state directory at jobs/<job-id>/work; your checkout is not switched out or cleaned up by the wrapper.

4. Poll with agy_status or block with agy_wait (seconds, max 300), then read agy_result / agy_review for the response, commits, diff and audit findings. agy_cancel stops a runaway job.

5. If you accept the work, merge the job branch yourself. Then call agy_cleanup; it deletes the branch only when no commit becomes unreachable. A squash or cherry-pick merge still needs force=true.

The full tool list is agy_start, agy_status, agy_wait, agy_result, agy_cancel, agy_list, agy_resume, agy_review, agy_cleanup, agy_usage. Exact parameters and error codes are in doc/reference/mcp-tools.md.

Safety notes

• There is no OS sandbox in this pre-release. agy runs directly on the host as your user and can read and write what you can. The wrapper provides branch/worktree isolation, environment secret sanitization and tamper detection, not containment. Do not point it at a checkout whose secrets you cannot afford to expose; use a throwaway clone or a dedicated branch when in doubt.

• What the wrapper writes: the state directory (jobs/<id>/work worktree, logs, job.json, locks), git metadata in the target repository (worktree registration and an .agy/ line in .git/info/exclude), and its own config when you create it.

• What it reads but never writes: a fixed set of host security files (~/.ssh/*, ~/.gnupg/*, shell rc files, ~/.gitconfig, ~/.netrc) hashed for tamper detection, and one agy session transcript under ~/.gemini/antigravity-cli for denied-call detail.

• Shutdown is not a kill switch. On stdin EOF or SIGTERM the server stops its supervisor threads without killing the background agy process group; the next startup reconciles jobs that are still running.

• Cleanup is dry-run-first. List first, then delete:

  python -m agy_mcp.cleanup_jobs --store ~/.local/state/agy-mcp --list
  python -m agy_mcp.cleanup_jobs --store ~/.local/state/agy-mcp          # dry run
  python -m agy_mcp.cleanup_jobs --store ~/.local/state/agy-mcp --yes    # delete

  cleanup_jobs only removes terminal job records whose worktree is no longer registered (it refuses a job whose worktree still exists) and it never deletes a git branch. cleanup_fixtures removes test-fixture rows only. Prefer agy_cleanup for a single job.

• The installer is dry-run-first and surgical. --dry-run changes nothing, it backs up dsh files to .bak before editing, and it refuses to run inside dsh.

Documentation

• doc/README.md — documentation index and reading order.

• doc/using/install.md — installation and client setup.

• doc/reference/mcp-tools.md — tool contracts.

• doc/design/spec.md — normative behavior contract.

• doc/developing/gates.md — commands a change must pass.

Contributing and security

See CONTRIBUTING.md for the development workflow and SECURITY.md for private vulnerability reporting.

License

Apache-2.0. See LICENSE.