An MCP (Model Context Protocol) server that wraps the Antigravity CLI (agy), so any MCP client (Claude Code, Cursor, Cline, and others) can run agy prompts, peer reviews, and follow-up turns as native tools.
Status: feature complete (stdio and HTTP transports, async and sync job lifecycle, model and session discovery, per-run controls and structured output, cross-platform builds) and verified against a live agy, with 1.1.15 the minimum supported version.
Why
Driving agy from a shell for automation has two recurring problems:
agy -p(print mode) reads stdin even when the prompt is passed with-p. If stdin is an open pipe that never closes, it blocks indefinitely. The fix is to always close stdin (</dev/null), which is easy to forget.- A review can run for many minutes. A single blocking call ties up the caller and can exceed a client's tool-call timeout with nothing recoverable.
agy-mcp solves both by running agy as managed, asynchronous jobs behind a small, typed tool surface, and by capturing output to disk, with a completed run's result and metadata fsync'd, so the result survives a client disconnect, a server restart, or a crash.
Every job runs agy --output-format stream-json, and the supervisor decodes that event stream as it arrives. That is where the conversation id, the response text, the failure message, and the token accounting all come from, so agy-mcp never has to infer any of them.
What it provides
agy_run/agy_status/agy_cancel: start anagyprompt, poll for completion, cancel if needed.agy_run_sync: start a prompt and wait for it inline (bounded, with MCP progress notifications); returns thejob_idto wait on or poll if it outlives the wait cap.agy_wait: block until an already-started job finishes (bounded, with MCP progress notifications); one call replaces anagy_statuspoll loop.list_models: enumerate availableagymodels, as the ids themodelparameter accepts plus their display labels.list_agents: enumerate availableagyagents, as the names theagentparameter accepts. Unlikelist_modelsthere is no id/label split, becauseagytakes an agent name verbatim; an empty list just means no agents are configured. Passcwd(the directory you giveagy_run) to include that repository's project agents from.agents/agents/; agy lists them only for a workspace directory, so withoutcwdthey are absent. On agy 1.3.4 and later a name that is not in the list fails the run before any model call, asfailedwithfailure_reason: agy_errorand an error that lists the available agents (MEASURED against agy 1.4.6); an older agy runs its default agent instead (agy changelog 1.3.4), so check the name withlist_agentsfirst.agy_usage: report the remainingagyquota per quota group (for example the Gemini pool) with a level ofok,low,criticalorexhausted. It spends no model quota. See Quota.list_sessions: list known conversations so review threads can be continued. An unfiltered call omits the ephemeral per-call workspaces the agy-openai-shim helper creates; pass adirto fetch a specific one.
agy_run and agy_run_sync also take optional per-run controls: pick the model, reasoning effort (low/medium/high), execution mode (accept-edits; plan is refused, see the constraints below), a named agent, sandbox terminal restrictions, and a json_schema to constrain the result to structured output. Those run-shaping values are forwarded to agy; idempotency_key is handled only by agy-mcp and is never forwarded.
For retry-safe job creation, supply idempotency_key when a transport failure could leave it ambiguous whether the run started. Reusing the same key with the same normalized request returns the existing job instead of starting another; using the key for a different request is rejected. The binding lasts while that job remains in the job store (24 hours by default), so this is transport-retry protection rather than a permanent business-level deduplication key.
For json_schema runs, agy-mcp returns AGY's terminal structured_output and fails closed when a successful terminal event lacks that field. It deliberately does not run a second local JSON Schema validator; schema conformance remains AGY's responsibility, while agy-mcp's responsibility is preserving and selecting the correct structured-result channel.
A delegated run should not rely on launching a long background shell command (a build, a test suite, a typecheck) and then waiting for it. In headless -p mode agy has no interactive loop to await one: after its agent goes idle it waits a bounded time for outstanding background tasks, then terminates any still running and exits, so a command that outlives that wait never returns its output to the agent and the run's answer is only progress narration. Before agy 1.2.9 the wait was about 5 seconds. From 1.2.9 it lasts until the run's --print-timeout deadline (agy-mcp passes the job timeout), capped at 30 minutes per agy's changelog, so a short background command now completes but one that outlives the job's budget is still cut off. The flip side is that a background command that never exits on its own, such as one waiting on an interactive prompt, holds the whole job open for as long as that wait lasts. Have the agent run any such verification in the foreground, or pass the results in the prompt. When agy does abort a run this way it still exits 0 cleanly (with a SUCCESS payload in the run MEASURED against agy 1.2.7); agy-mcp detects the abort from agy's stderr and reports the run as failed with failure_reason: background_aborted, carrying the narration as a partial result, so a caller can tell it apart from a real answer rather than consuming a phantom success. If agy-mcp's own hard kill lands before agy gets there, the run is reported with failure_reason: timeout instead.
A delegated run should likewise avoid spawning an internal subagent to do the real work and then waiting for it. When agy's agent delegates to a subagent, the subagent's output is not streamed on the parent run's stdout, so agy can finish and report a SUCCESS payload whose response is only the parent's progress narration ("waiting for the reviewer subagent to complete") while the actual result is lost. Unlike the background-shell abort above, this leaves no distinguishing signal in agy's output: the parent's own token accounting counts the subagent's generation as ordinary output tokens, which is indistinguishable from a normal tool-heavy run that ends in a short answer, so agy-mcp cannot reclassify it without also downgrading genuine short answers. Keep the work in the parent run instead: instruct the agent to write its findings directly rather than delegate, or continue the same conversation_id with that instruction to recover the answer on the next turn.
Pass model as an id (gemini-3.1-pro-high), the form list_models returns in its models field, not as the display label agy prints beside it (Gemini 3.1 Pro (High)). agy takes either form on its own, but every display label in the agy 1.1.11 catalog was refused once effort was set too, at every effort. The same applies to AGY_MCP_DEFAULT_MODEL. Not every id accepts every effort either, and some accept none, so omit effort unless you need a specific one.
Session continuation rides agy's own durable conversation store (--conversation <id>), so threads survive across calls without keeping a process warm.
A delegated run can modify your files. agy is launched with
--dangerously-skip-permissions, so the agent it starts can read and write anywhere under
cwd and under every directory passed in dirs, without prompting. For a review that must
not touch the repo, say so explicitly in the prompt. The tools declare this on the wire: agy_run and
agy_run_sync are annotated destructiveHint: true / openWorldHint: true, agy_cancel is
destructiveHint: true / idempotentHint: true, and agy_status, agy_wait, agy_usage, list_models,
list_agents and list_sessions are readOnlyHint: true. Annotations are hints, so a client is free to
ignore them; one that does gate confirmation on them may stop prompting for the read-only
tools.
Project rules load by default. agy-mcp passes the run's cwd as an --add-dir, which makes it an agy workspace, so the project's AGENTS.md applies to the delegated run, including one at the repository root when cwd is a subdirectory (#188). Whether the flag is needed depends on the agy version. MEASURED against agy 1.2.9 (issue #188): in print mode, running agy inside cwd did not make it a workspace, so no rules loaded without --add-dir, and agy's /hooks listing showed the hooks in the workspace's .agents/hooks.json as enabled only with it. MEASURED against agy 1.2.16 and 1.4.8: cwd is a workspace without --add-dir. Its AGENTS.md (including the repository root's, from a subdirectory) is applied and its .agents/hooks.json hooks run, with or without the flag. Which release changed this is not measured. So project_rules: false only omits the implicit --add-dir: on agy versions that need the flag that keeps the rules and hooks out, and on 1.2.16 and 1.4.8 it does not, and neither has a flag that turns them off. Do not rely on it to isolate a run from a repository you do not trust. Each directory in dirs is passed as given and is a workspace in its own right, so listing cwd there makes it a workspace even with project_rules: false, and a repository passed only in dirs also has its rules applied and its hooks run (MEASURED against agy 1.4.8). The one shape measured to keep a repository's rules and hooks out on agy 1.4.8 is a cwd that is an empty directory outside any repository, with the repository left out of dirs and its files named by absolute path in the prompt; reading them that way worked, while writing outside the workspace was not measured. continue_latest and list_sessions then key on that directory rather than the repository, and list_agents for it shows none of the repository's project agents.
Two transports run the same core:
- stdio (default): zero-config, one line in your MCP client config.
- Streamable HTTP (opt-in): a long-lived, loopback-only daemon for multi-client use. See HTTP mode.
Requirements
-
agy 1.1.15 or newer, on
PATHor configured explicitly viaAGY_MCP_AGY_PATH. This is a hard floor, not a recommendation. The floor is 1.1.15 because that release fixed streamed text corrupting non-ASCII characters into replacement characters in the--output-format stream-jsontext deltas. Those deltas are the text agy-mcp falls back to for a run cut short before agy's result event, or one agy completes with an empty response: on an older agy that text is lossy for non-ASCII content (another language, emoji, box drawing, unicode in code), and agy-mcp cannot repair bytes it never received intact. Earlier, lower floors it subsumes: 1.1.8 added--output-formatto print mode and agy-mcp drives every job through thestream-jsonformat it introduced; 1.1.10 is the first release where the run-shaping flags agy-mcp forwards in headless-p(--modeland--effort) are honored rather than silently ignored; 1.1.12 added the machine-readablemodelsenvelope (command.data.models) thatlist_modelsdecodes into ids and labels instead of tab-splitting text, and fixed--modebeing ignored in headless-p; and 1.1.14 made a failed language server exit non-zero instead of reporting success, so agy-mcp records that failure as failed (all per agy's changelog). Older builds are refused rather than degraded. agy 1.2.9 or newer is worth having if you run jobs in parallel: per its changelog it fixed a conversation-database corruption risk in which checking the database file for write access could drop file locks that concurrent agy processes held on the same file. Whether parallel agy-mcp jobs actually share such a file has not been measured.The version is checked once per process, the first time a tool actually needs agy, and the verdict is cached. A binary that is too old is reported as
agy 1.1.15 or newer is required ...; found 1.1.7 at /usr/local/bin/agy. A failed check is deliberately not cached, so upgrading agy is picked up without restarting the server.A missing
agydoes not stop the server from starting.initialize,tools/list, andlist_sessionsnever exec it, so the lookup is deferred: the server starts, logs a warning to stderr, serves discovery normally, and the tools that do need the binary (agy_run,agy_run_sync,agy_usage,list_models,list_agents) fail per call withagy not found on PATH; set AGY_MCP_AGY_PATH. Anagyinstalled later is picked up without restarting the server. An explicitAGY_MCP_AGY_PATHis treated differently: it is a claim about one specific binary, so a typo or a non-executable target still fails fast at startup.
Note: every job spawns a fresh
agyprocess, which on startup launches whatever MCP servers are configured in agy's ownmcp_config.json. Peer-review and automation runs usually do not need those servers, and a slow or hanging one adds latency to every job. agy 1.0.7+ bounds this with a per-server launchtimeout(set-1to disable it). If startup is slow, give the unneeded servers atimeoutin agy'smcp_config.json, or point agy at a trimmed config.Note (continuation): a follow-up turn runs
agy --conversation <id> -p <prompt>, and the job result is theresponsefield of agy's terminalresultevent. Verified against 1.1.10: a resumed run returns only the new turn and echoes the same conversation id, withnum_turnsincremented.Note (auth): agy-mcp passes its own process environment through to every spawned
agy, so agy's normal sign-in is used by default. For headless or daemon deployments (HTTP mode, cron) where no browser is available, setAGY_ADC_AUTH=1in the server's environment to have agy sign in with Google Application Default Credentials (agy's changelog names the variable from 1.3.3 on; ADC sign-in itself arrived in 1.1.10). The variable does not create credentials: set them up with Google's tooling, for examplegcloud auth application-default loginon a host with a browser or a service-account key named byGOOGLE_APPLICATION_CREDENTIALSon one without (agy 1.1.12 made service-account logins work without extra configuration, per its changelog). agy does not readUSE_ADC: setting it changes nothing (MEASURED against agy 1.4.8). On a host that had an ADC credentials file (its validity not checked) and normally signs agy in another way, setting the variable made every run fail (MEASURED against agy 1.4.8:agy -pexits 1 withError: authentication required. Run 'agy' to log in.,agy modelswithPlease sign in to view available models. Launch the CLI without arguments to sign in., andagy-mcp doctorfails its auth check). agy's own advice there is to runagyinteractively to sign in; its first-run setup for ADC shows the Google Cloud Platform Terms of Service (changelog, 1.4.1), and whether one interactive sign-in clears the failure for later headless runs is NOT MEASURED. agy 1.4.7 fixed skills, rules, custom agents, plugins, plugin MCP servers and hooks not loading under ADC sign-in (changelog, 1.4.7); which earlier releases had that bug is not stated. No agy-mcp flag is needed; unset the variable to fall back to the other sign-in methods. agy-mcp recognizes that failure: when agy fails a run with an ERROR result, or exits non-zero without a SUCCESS result, the failure is not a quota wall, and the result's error or stderr has the line above (or, per the changelog for 1.3.3, ), a run with no result text gets a note saying a person must sign agy in on the host running agy-mcp (or check the ADC credentials when is set). Its stays . warns when is set without on, and when is on with an agy below 1.4.7 (doctor counts only and as on, the two spellings MEASURED against agy 1.4.8). It reads its own environment, so run it with the server's environment (the same unit file, container or shell).
Install
Homebrew (macOS / Linux)
brew install tphakala/tap/agy-mcp
This installs the prebuilt release binary (macOS and Linux, amd64 and arm64) from tphakala/homebrew-tap; upgrade later with brew upgrade agy-mcp. The tap formula is regenerated on every release, so upgrades track new versions as they ship.
Go install
go install github.com/tphakala/agy-mcp/v2@latest
The module path carries a /v2 suffix from v2.0.0 on, as Go requires for a major version. go install github.com/tphakala/agy-mcp@latest still resolves, but to the last v1 release.
Use with Claude Code (stdio)
claude mcp add agy -- agy-mcp
Or add to your MCP client config:
{
"mcpServers": {
"agy": { "command": "agy-mcp" }
}
}
Tools
agy_run(prompt, model?, effort?, mode?, agent?, sandbox?, dirs?, project_rules?, conversation_id?, continue_latest?, cwd?, timeout?, json_schema?, idempotency_key?, priority?)->{ job_id, conversation_id?, state, quota? }agy_run_sync(prompt, model?, effort?, mode?, agent?, sandbox?, dirs?, project_rules?, conversation_id?, continue_latest?, cwd?, timeout?, json_schema?, idempotency_key?, priority?, wait?)->{ job_id, state, elapsed, result?, error?, failure_reason?, recovery?, retryable?, error_id?, conversation_id?, model?, partial?, num_turns?, usage?, step_type?, quota?, note? }agy_status(job_id)->{ state, elapsed, result?, error?, failure_reason?, recovery?, retryable?, error_id?, conversation_id?, model?, partial?, num_turns?, usage?, step_type?, quota? }agy_wait(job_id, wait?)->{ job_id, state, elapsed, result?, error?, failure_reason?, recovery?, retryable?, error_id?, conversation_id?, model?, partial?, num_turns?, usage?, step_type?, quota?, note? }agy_cancel(job_id)->{ state }agy_usage(max_age?)->{ checked_at, groups }, each group{ name, description?, level, remaining_percent, window, reset_time?, buckets }list_models()->{ models, model_details }list_agents(cwd?)->{ agents }list_sessions(dir?)->{ sessions }
list_sessions without dir omits the ephemeral per-call workspaces the agy-openai-shim helper creates: the server never starts a run in one and on a busy cache they can outnumber the real workspaces many times over (#167). Pass a dir to fetch a specific workspace, transient or not; the filter is canonicalized (made absolute, with best-effort symlink resolution) before matching.
models holds ids alone, so its entries can be passed straight to model; model_details pairs each id with the display label agy prints for it, in the same order, for showing a readable name. Through v2.1.0 models carried each agy models row whole, which was a tab-joined id<TAB>label string that agy does not accept as a model at all, so a client had to split it and pick a column (#135).
usage is agy's own token accounting (input_tokens, output_tokens, thinking_tokens, cache_read_tokens, total_tokens), and together with num_turns it appears once a run reports a terminal result.
model echoes the model id agy-mcp resolved for the run (the one you passed, or AGY_MCP_DEFAULT_MODEL, reduced to its id), so a caller can confirm which model actually ran. It is absent when no model was pinned and agy ran on its own default.
A run that ends badly still hands back whatever it managed to say, so result is set on failed and cancelled jobs too and is worth reading rather than discarding. partial is what says whether to trust it as the final answer, and it follows from where the text came from (and from agy's stderr notices, described below) rather than from the state. When such a run produced no text at all but still named a conversation, recovery usually carries a short note on continuing that conversation instead of restating the task. A background_aborted run gets no such note, because simply carrying on with the same task would launch the same background command again; its error says to re-run with the verification in the foreground instead. A quota_exhausted failure is an exception the other way: its recovery note advises waiting for the reset and retrying even when no conversation was named (see failure_reason below). A run that agy could not start or continue because it is not signed in, or because its sign-in expired, is another: it also gets a recovery note without a conversation, saying a person must sign agy in on the host running agy-mcp, and its failure_reason stays agy_error. When retryable is false (see below), the note instead says to fix the cause rather than continue the conversation (a sign-in note keeps its sign-in advice), and a quota_exhausted note keeps its wait-for-reset advice without conversation_id but adds that the cause may need fixing first when error names no reset time.
failure_reason classifies a failed job into one stable, machine-readable category so a caller can branch on the cause without scraping error. It is present only when state is failed (a cancelled job is already named by its state, and a running or done one has no failure), and the set is closed, so treat any value you do not recognize as unknown. The values are quota_exhausted (agy hit a provider quota, rate-limit or AI credits wall), timeout (the run outlived its timeout: agy-mcp killed it, or agy's own --print-timeout expired mid-turn and agy returned only what it had, possibly nothing), spawn_failed (the agy binary could not be started, or agy itself exited 127, which shares the same exit sentinel), agy_error (agy itself reported an error, exited non-zero, or returned an indeterminate result), interrupted (the job process vanished without writing a result), background_aborted (agy ended the run itself, by a clean exit or in a job recovered from its result after its supervisor died, but its stderr shows it went idle with outstanding background shell tasks and killed them at exit, so the response is only progress narration rather than completed work; re-run with any verification in the foreground), and unknown (a failure fitting none of the above, for example its output could not be read). quota_exhausted is the one that is transient rather than fatal (unless agy reports it with retryable false, see below): error keeps agy's message, including the reset window when agy gives one (agy-mcp does not parse it out; agy_usage reports quota reset times), and recovery says to wait for the reset and then retry, reusing conversation_id when one was named, unless agy reported the error with retryable false. So a caller that hits a quota wall can back off until it clears instead of treating the run as a hard failure.
retryable and error_id come from the structured AGY_ERROR: line agy writes to stderr when it fails a request (MEASURED against agy 1.2.9 and 1.3.1 for a model not available in the account's region: exit 3, retryable: false; #183). They are present only on failed jobs whose stderr carried a well-formed line; absent means agy gave no verdict, not that the failure is permanent. When that line's canonical status is RESOURCE_EXHAUSTED, the job is reported as quota_exhausted even if the message wording is not recognized; this follows agy's status naming and has not been checked against a captured quota error. agy's raw short_error text carries the cloud project and region, so it is not copied into these fields, and when error falls back to the stderr tail (a non-zero exit whose payload gave no message, or exit 127) each line in that tail that starts with AGY_ERROR: is reduced to its canonical status, for example AGY_ERROR: NOT_FOUND (code 404), or left out when it cannot be read; failure_reason is still classified from the unreduced text.
It is true when the text was reconstructed from the streamed events, which happens when agy never reported a terminal result (a clean exit whose final event never arrived, a cancel, a timeout, a supervisor that died mid-stream) and also when agy did report one but the authoritative result channel was empty, so fallback text is all that remains. It is likewise true when agy reported a terminal result that was not a success, in which case the text is only what the run had produced by the time it stopped, and when agy marked the result a success but its stderr shows it ended the run early (its own --print-timeout expired mid-turn, or it killed outstanding background tasks). That applies even after a hard kill: a response agy wrote when its own --print-timeout expired is flagged partial. For a non-schema run, a SUCCESS response is authoritative; for a json_schema run, only SUCCESS structured_output is authoritative, and a retained response is diagnostic/partial when that structured result is missing. An authoritative result stays non-partial even if the process is then cancelled or killed; the exceptions are a timed-out run whose stderr shows agy's own --print-timeout had already expired, and a job recovered from its result after its supervisor died whose stderr shows agy ended the run early.
Parameter and result fields carry their own descriptions in the tool schemas, so a client sees
them without consulting this file. The constraints worth knowing up front: conversation_id
and continue_latest are mutually exclusive (setting continue_latest true alongside a
conversation_id is an error); timeout is a Go duration and a value above 24h is rejected
outright, and on expiry the job normally ends in state failed with failure_reason: timeout,
because agy-mcp kills the agy process tree (if agy's own
--print-timeout fires first, agy stops the turn itself and any text it had comes back as a
partial result); effort, when set, must be
low, medium or high, and mode, when set, must be accept-edits, with any other
value rejected before the run starts. plan is refused because agy ignores --mode plan while
slash command expansion is disabled, which agy-mcp does on every run so prompts stay literal, so the
run would apply edits instead of only planning (MEASURED against agy 1.1.15, 1.1.27, 1.4.6 and 1.4.8,
#219); to keep a run from editing, say so in the
prompt. accept-edits is forwarded as given; under --dangerously-skip-permissions, which every run
passes, it made no observable difference compared with a run without
--mode (MEASURED against agy 1.4.8: a file write and a shell command were applied either way). wait defaults
to 90s and is silently clamped to that same ceiling. That 90s default is kept below the roughly
120s per-call timeout common MCP clients (Claude Code included) impose, so agy-mcp's still-running result reaches
the caller inline instead of being lost to a client-synthesized timeout (set AGY_MCP_SYNC_WAIT_CAP
to a Go duration to raise or lower the ceiling for a client with a different per-call limit), and it
bounds only the inline wait, never the job itself.
agy_cancel is asynchronous, so it usually returns running and the job settles to cancelled
a moment later. A prompt is sent to agy literally: a leading slash-command or skill name
(a prompt beginning with /) is treated as text rather than expanded, so caller input means
exactly what it says regardless of the installed agy version.
A fresh agy_run (no conversation_id, no continue_latest) reports the conversation agy
created for it. agy names the conversation in the init event of its stream, which arrives
about a second after the process starts, so agy_run waits briefly (up to 2s) for it and
returns a real conversation_id. If the wait expires the field comes back empty and
agy_status supplies it moments later; either way the thread can be continued.
agy_run_sync does not pay that wait: it takes its conversation_id from the status it
is already polling. That is also what makes its wait cap honest, because the
conversation-id wait used to run before the inline wait's deadline was set, so a short
wait could be overrun by up to the 2s budget. The trade is that a wait shorter than
agy's init latency now returns an empty conversation_id, which agy_status supplies.
Fresh runs are not serialized. Any number of them can run in one directory at the same time, bounded only by the global concurrency cap. Earlier versions refused a second fresh run in a directory that already had one, because the conversation id had to be inferred by diffing agy's shared conversation cache and that inference was only sound while nothing else could touch the same entry. Reading the id from agy's own stream removes the ambiguity and the restriction with it.
What is still serialized is a conversation: two runs continuing the same conversation_id
cannot overlap, because concurrent agy sessions on one conversation trigger a known session-lock
hang in agy itself. The second is refused with a conflict error rather than queued. That gate is
rebuilt at startup from jobs whose supervisor outlived a server restart, so it holds across
restarts.
Conversation serialization also holds across separate agy-mcp processes, which matters in
stdio mode, where each MCP client session spawns its own process sharing one
AGY_MCP_STATE_DIR. A per-conversation advisory lock (flock on a file under
<state-dir>/locks/) stops two sibling sessions from continuing the same conversation at once.
The global concurrency cap, by contrast, is enforced per process: with N client sessions each
capped at the configured limit, up to N times that many runs can be in flight. Lock files are
left in place by design (unlinking a flock file races), so locks/ keeps one empty file per
conversation ever locked.
Two caveats, both now scoped to continuations only. AGY_MCP_STATE_DIR must live on a local
filesystem that supports flock (not NFS, where flock may be a no-op or fail); a continuation
is refused rather than started if the lock cannot be taken, so cross-process exclusion can never
silently lapse. And across a server restart there is a brief window, while the manager process is
down, before it re-takes the locks for jobs whose supervisor outlived it; a sibling process that
continues the same conversation during that window is not blocked. The in-process gate is always
restored at startup, so this gap is limited to the restart window itself. Fresh runs take no lock
at all and are unaffected by either caveat.
Quota
agy_usage runs agy --output-format json -p /usage and returns the quota per group (the Gemini pool, shared by every Gemini model, Flash and Pro alike, is one group; Claude and GPT models are another, MEASURED against agy 1.2.16; only Gemini models are matched to a group, so a run on any other model is never refused). That invocation starts no agent turn and spends no model quota (agy changelog 1.1.11; MEASURED against agy 1.2.16, which also measured that adding --disable-slash-commands turns /usage into a model prompt, so the probe never carries it, and a reply that shows a model turn switches probing off for the rest of the server process). The probe runs in its own session because agy 1.2.x otherwise stops on SIGTTOU when it shares a controlling terminal.
Each group has a level from its tightest window (usually the 5h or the weekly limit): exhausted at 0, critical below 5 percent remaining, low below 25 percent, otherwise ok. A window whose reset_time has passed counts as full, so a stale reading never reports a quota that has since refilled as low. remaining_percent is rounded down and the level is the authority. Thresholds are set with AGY_MCP_USAGE_LOW and AGY_MCP_USAGE_CRITICAL.
Readings are cached in memory per server process (60 seconds by default; max_age sets how old a reading may be, from 10 seconds up, and a younger reading is reused), concurrent callers share one probe, and a failed probe is remembered for 30 seconds. With AGY_MCP_USAGE_INTERVAL above zero (5 minutes by default) the server also refreshes the reading in the background. agy_run, agy_run_sync, agy_status and agy_wait results carry a compact quota field read from that cache; it never waits on agy and is absent when there is no reading younger than twice the interval (at least 10 minutes). Several servers (one per client session) each probe on their own.
priority: optional on agy_run or agy_run_sync marks work that may be skipped, such as a peer review or a second opinion. When the run's model belongs to a group at low, critical or exhausted, the run is refused before any job starts, as a tool error naming the group, level, remaining percent and reset time. The refusal creates no job, so failure_reason is unchanged; report the skip instead of retrying. The guard fails open: no reading, a reading that is too old, a model outside a known group (or an omitted model with no AGY_MCP_DEFAULT_MODEL), or a failed probe with no trusted earlier reading never refuses (an earlier reading inside that window still applies), and priority: normal (the default) always runs. priority is not part of the idempotency_key match: a retry whose key already names a job returns that job whatever its priority and the current quota.
Completion wake for Claude Code
Claude Code does not surface MCP server notifications to the model: progress notifications are UI-only, and there is no server-initiated push that can wake the model when an async job finishes. Polling agy_status after agy_run is the protocol-level baseline. agy-mcp ships a hook bridge that turns job completion into a real wake instead, built on Claude Code's asyncRewake hook mechanism: a background PostToolUse hook that exits with code 2 wakes the model with the hook's stderr as a system reminder.
Add to your Claude Code settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "mcp__agy__agy_run(_sync)?",
"hooks": [
{ "type": "command", "command": "agy-mcp hook-wait", "asyncRewake": true, "timeout": 3700 }
]
}
]
}
}
How it behaves:
- After every
agy_run, the hook waits (in the background, off the session's critical path) for the job's completion sentinel and then wakes Claude with a one-line message naming thejob_idand final state, prompting the model to callagy_statuswhen the result is actually ready. agy_run_synccalls that returned their result inline produce no wake; a sync call that overran its wait cap (and so returned a still-running job) gets the same completion wake asagy_run.- A finished job produces no wake when a tool has already returned its outcome to the session:
agy_waitandagy_statusrecord acollectedmarker in the job directory when they return a terminal state, and hook-wait exits 0 silently if the marker is present. The marker is written as the tool returns the outcome, so hook-wait allows up to one second for it to appear before waking. The marker records that the tool returned the outcome, not that the client received it, so a call abandoned in transit can leave a finished job without a wake.agy_cancelrecords a separatedismissedmarker when it asks a job to stop, and hook-wait honours it only if the job then endscancelled, so a job that finishes on its own before the stop lands still wakes. One narrow case follows from this: a job that had already produced its complete answer and then exits non-zero under the cancel signal still reads ascancelled(with that answer kept, seepartial), so it gets no wake either; read a job you cancelled withagy_statusbefore re-running it. Every other finished job still wakes, including a job nobody collected, a job cancelled without anagy_cancelrequest, and one whose wait overran while it was still running. The marker is per job, not per session, so a job collected by one session (or subagent) is not woken for in another. - When the PostToolUse payload names the calling subagent (
agent_type), the wake message says the job was started by that subagent, so a parent session can tell it is not its own. Per Claude Code's hooks documentation the field is present only inside a subagent call. MEASURED against Claude Code 2.1.289: absent from a main-thread payload,general-purposein a foreground or background subagent's payload, for both a Bash and anmcp__agy__tool call. - On timeout (default 1h,
-timeoutto change) the hook still wakes Claude, reporting the job as still running, so a long job is never silently lost, provided the outer hooktimeoutexceeds hook-wait's own-timeout(see thesettings.jsonnote below). An externally interrupted wait (a SIGINT or SIGTERM delivered to hook-wait) also wakes, with a distinct "wait interrupted" message pointing at and , rather than exiting silently and dropping the owed wake. On any internal error the hook exits 0 silently; it can never disrupt the tool call it observes. The hook-level in (3700 above) must exceed hook-wait's own (1h by default) by more than the one-second marker grace plus a poll interval (a quarter of a second), because a job that finishes on the last poll spends both after the timeout; the 100 seconds of margin above is ample. With that margin hook-wait's internal timeout always fires first and reports the wake itself; if the outer is equal or lower, Claude Code kills the hook process first and the exit-2 wake is lost, silently defeating that guarantee.
Two related subcommands, useful beyond Claude Code:
agy-mcp wait-job [-timeout 1h] <job_id>blocks until the job is terminal and prints the final state word (done,failed, orcancelled) to stdout. Exit codes: 0 terminal, 1 error, 2 usage, 3 timeout, 130 interrupted. It needs only the job state directory, not the agy binary, so it works in minimal environments.agy-mcp hook-wait [-timeout 1h]is the hook entrypoint described above: it reads the PostToolUse payload from stdin, so it is not useful to invoke by hand, but it is a single self-contained binary call, no shell wrapper or jq required, and it works on Linux, macOS, and Windows. The file-based wake contract is exercised by tests on all three platforms; the signal-interrupt wake (SIGINT/SIGTERM) is a POSIX behavior and is tested there.
Preflight (agy-mcp doctor)
agy-mcp doctor runs the read-only checks a run depends on and prints a one-line verdict for each, so a broken setup names its own cause instead of surfacing as a downstream tool error (for example list_models failing when agy is missing from PATH or not authenticated). It checks that the agy binary resolves, meets the version floor, and is reachable and authenticated (a model listing); that the state directory is writable; names where each effective setting came from (an environment variable or the default) without printing any secret value; warns when the environment selects ADC sign-in in a way that does not work as intended (USE_ADC without AGY_ADC_AUTH, or AGY_ADC_AUTH on an agy below 1.4.7; see the auth note above); and reports any stale jobs a prior crash left behind. It never starts a job or mutates job state.
The exit code is meant for a setup script or CI: 0 when nothing is broken (a warning does not count, and a fresh install with no jobs passes), 1 when a check failed, 2 on a usage error. A WARN line (leftover jobs the periodic GC will reap, or an ADC environment caveat) is information, not a failure.
On POSIX, both wait subcommands install their SIGINT/SIGTERM handler only after parsing flags, resolving the job state directory and building the wait manager (and hook-wait also reads its payload from stdin first), so a signal sent immediately after launch can land before the handler exists and kill the process outright, losing the interrupt exit code. A parent that intends to interrupt a wait can close that window by setting AGY_MCP_WAIT_READY_FILE: the subcommand creates that file the moment the handler is in place, so waiting for it to appear makes the signal deliverable. Leave it unset and nothing is written. Three caveats, because existence is the entire signal: the path must be absolute (a relative one resolves against each process's own working directory, and hook-wait runs from the session cwd), it must be fresh and unique per invocation (a file left from an earlier run satisfies the wait immediately and hands back the race), and the parent still needs its own timeout, since both subcommands have exit paths that return before any handler is armed. An existing file at that path is refused rather than overwritten, so pointing the variable at something that matters destroys nothing; that protects the file, not the handshake, which is why the path has to be fresh.
MCP clients other than Claude Code get the same no-polling benefit in-protocol: call agy_wait with a job_id from agy_run (or from an agy_run_sync that outlived its inline wait) and the tool blocks (bounded by wait, default and cap 90s, raise or lower with AGY_MCP_SYNC_WAIT_CAP) until the job finishes. Re-issue agy_wait with the same job_id if a single bounded call is not enough; each call blocks another window rather than re-running the job.
HTTP mode
agy-mcp -http 127.0.0.1:8765
HTTP mode is opt-in and only accepts a loopback bind address (localhost, 127.0.0.1, or ::1). A non-loopback address (including :8765, which binds all interfaces) is refused at startup, so it cannot be accidentally exposed.
Two extra hardening layers are always available:
- Origin/CSRF protection is always on. A state-changing cross-origin browser request (one carrying a cross-site
Sec-Fetch-Siteor a mismatchedOrigin) is rejected with403. Normal non-browser MCP clients (Claude Code, Cursor, the go-sdk client) send noOriginheader and are unaffected. - Optional bearer token. Set
-http-token <token>(orAGY_MCP_HTTP_TOKEN) to requireAuthorization: Bearer <token>on every request; a missing or wrong token gets401. The flag overrides the env var. Off by default, so the bare loopback mode stays unauthenticated.
agy-mcp -http 127.0.0.1:8765 -http-token "$(openssl rand -hex 32)"
Upgrading from v2.1
Behaviour change to check your client against: list_models used to return each agy models row whole in models, as a tab-joined id<TAB>label string. It now returns the id alone, and pairs each id with its display label in the new model_details field. No type on the wire changed, only the values, so a client that renders models to a human now shows a slug and should read model_details[].label instead, and one that split each entry on the tab will find nothing to split. A stored old value passed back as model still works: the server reduces a whole row to its id before running it.
Upgrading from v1
v2 requires agy 1.1.15 and drives it through --output-format stream-json. The upgrade is safe to do in place, but two things are worth knowing.
Stop the server before replacing the binary. The supervisor is the same agy-mcp binary re-executed as agy-mcp run-job <dir>, so replacing it under a live v1 server pairs an old manager with a new supervisor. The supervisor detects that case and asks agy for the event stream anyway, so no result is lost, but a v1 manager and a v2 process sharing one AGY_MCP_STATE_DIR briefly disagree about cross-process locking, and a v1 run's conversation id can be misattributed in that window.
Jobs already in the state directory keep working. A job dir written by v1 loads cleanly (the two removed meta.json fields are simply ignored) and its result is still reported in full. Two degradations apply until those jobs age out of the 24h TTL:
- A v1 fresh run may report no
conversation_id. v1 recovered it by diffing agy's conversation cache, and v2 has no such path. Recover the thread withlist_sessionsif you need it. - Cancelled and interrupted v1 jobs behave as before; only the id is affected.
Behaviour changes to check your client against: agy_run now blocks up to 2s waiting for agy to name the conversation, instead of returning instantly; fresh runs in the same directory no longer conflict, so anything that relied on that conflict error as a mutex now gets real concurrency (and agy runs with --dangerously-skip-permissions, so concurrent runs edit one working tree); and list_models is now refused on an agy older than 1.1.15, even though agy models itself would work there.
Configuration
Development
Build, test and lint commands, the code layout and the conventions a change follows are in AGENTS.md.
License
MIT. See LICENSE.
