This MCP server turns the Antigravity CLI into sub-agent tools for delegating, monitoring, and managing agent tasks.
Delegate coding tasks with general_task in accept-edits mode, or read-only exploration/diagnosis with explore_task in plan mode.
Run delegated tasks synchronously and wait for the final report, or start them in the background and collect results later.
Configure runs with prompt, cwd, model, effort, agent profile, project, extra directories, sandboxing, auto-approval, edit scope, idle timeout, and conversation resume.
Use watch_task to inspect live/recent transcripts, poll progress, wait for completion, or cancel runs owned by the server process.
Use list_models and list_agents to discover accepted model IDs and custom agent profiles.
Get back task status, response, token usage, files touched, transcript/receipt paths, and audit details such as denied actions or scope violations when applicable.
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-agent-mcp Fix the failing auth tests and summarize the files you changed"
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.
An MCP server that turns the Antigravity CLI (agy) into five sub-agent tools.
You delegate a task, the call blocks, and you get the sub-agent's final report back.
Several delegations can run at once, each with its own transcript and result.
Requires Node >= 22.6 and an authenticated agy CLI.
npm install -g agy-agent-mcpRegister with OpenCode, Claude Code, or Antigravity itself:
# OpenCode
opencode mcp add agy -- agy-agent-mcp
# Claude Code
claude mcp add agy -- agy-agent-mcp
# Antigravity
agy mcp add agy-agent agy-agent-mcpIf agy is not on PATH, add --env AGY_BIN=/path/to/agy to any of the above.
OpenCode: pass --global to mcp add to register once for every project (writes ~/.config/opencode/opencode.json). Project configs defining the same server name override the global entry, so remove per-project agy blocks after switching.
After upgrading the installed package, restart the MCP client or reload its catalog (opencode api post /api/location/reload -d '{}' for OpenCode) — sessions spawned before the upgrade keep replaying the old boot failure otherwise.
From a local checkout (npm install first): opencode mcp add agy -- "$(pwd)/bin/mcp.mjs".
Related MCP server: sub-antigravity
Call general_task to delegate a coding task and wait for the final report:
{
"name": "general_task",
"arguments": {
"prompt": "Fix failing tests in test/parser.test.ts and verify the build passes",
"cwd": "/path/to/project"
}
}The call blocks until the sub-agent finishes and returns its summary:
{
"task_id": "task_a1b2c3d4",
"status": "success",
"response": "Fixed the off-by-one error in src/parser.ts and verified all tests pass.",
"usage": {
"input_tokens": 12450,
"output_tokens": 830,
"total_tokens": 13280
},
"files_touched": ["src/parser.ts", "test/parser.test.ts"],
"conversation_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"stream_file": "/tmp/agy-agent-mcp/tasks/task_a1b2c3d4.stream",
"transcript_file": "/tmp/agy-agent-mcp/tasks/task_a1b2c3d4.ndjson"
}A refused call returns {"error": "..."} with isError: true, the message names the offending argument, and nothing is spawned:
{
"error": "missing required argument: prompt"
}A failed run comes back with isError: true and status of error, timeout or quota_error, and error carries the CLI's own message.
Tool | Mode | Default Effort | Purpose |
|
|
| Delegate a coding task that may edit files and wait for the report. |
|
|
| Delegate a read-only diagnosis or exploration task without editing files. |
| — | — | Inspect live transcripts, poll progress, collect results, or cancel runs. |
| — | — | List model IDs accepted by the |
| — | — | List custom agent profiles accepted by the |
general_task and explore_taskgeneral_task runs in accept-edits mode (it may edit files), default effort: "medium".
explore_task runs in plan mode (read-only), default effort: "low".
Everything else is the same for both:
prompt (string, required): Full, self-contained task description for the sub-agent.
model (string, optional, default: CLI default): Model ID to use (e.g. gemini-3.8-flash).
effort (string low|medium|high, optional): Reasoning effort tier ("medium" default for general_task, "low" for explore_task).
agent (string, optional, default: CLI default): Antigravity agent profile (see list_agents).
cwd (string, optional, default: server cwd): Project directory for the delegated task.
background (boolean, optional, default: false): Start task detached in background and return handle immediately.
timeout_ms (integer 0..3600000, optional, default: 900000): Idle timeout in ms before killing silent child (0 disables).
edit_scope (array of strings, optional, default: unset): Paths defining expected edit boundary for change auditing.
add_dirs (array of strings, optional, default: unset): Extra directories to add to workspace (--add-dir).
sandbox (boolean, optional, default: false): Enable Antigravity terminal command sandboxing (--sandbox).
auto_approve (boolean, optional, default: false): Pass --dangerously-skip-permissions to stop headless auto-denials.
project (string, optional, default: unset): Antigravity project ID or name.
conversation_id (string, optional, default: unset): Existing Antigravity conversation UUID to resume.
A tier-carrying model ID (e.g. gemini-3.8-flash-high) already encodes its tier and must not be paired with a conflicting effort.
Headless runs never prompt: tools requiring user confirmation are denied automatically and surfaced in denied_actions. Add rules under permissions.allow in your Antigravity settings.json to grant access.
watch_taskReads recent activity, polls progress, collects complete results, or stops runs:
stream_file (string, optional, default: latest run): State path, task_<id>.stream filename, or task ID.
tail_lines (integer 0..2000, optional, default: 400): Trailing transcript lines to return (0 for all).
wait (boolean, optional, default: false): Wait for run to finish and return complete final result in one call.
cancel (boolean, optional, default: false): Stop the running task immediately. Cannot combine with wait: true.
list_modelsLists model IDs accepted by model. Takes no arguments (any argument is refused).
Output: Raw CLI output in models and parsed model names in model_ids.
list_agentsLists agent profiles accepted by agent (rejects any arguments).
Output: Configured custom agent profiles in agents.
Way 1 — just delegate: The call blocks until the sub-agent finishes, and you get the final report back.
Way 2 — delegate and collect later: Pass background: true to receive a handle immediately, then:
watch_task({ stream_file, wait: true }) collects the complete result in one call without polling;
watch_task alone polls live transcript lines and the step digest while running;
cancel: true stops the in-flight child process.
Several delegations can run concurrently, each with its own transcript and result. When runs share a git working tree, files_touched and scope_violations may include other runs' changes, which the result flags with audit_note. A wait for a run owned by another server process is refused with an error envelope telling you to poll instead; a cancel for such a run is reported as ignored, with a hint that the run belongs to another process.
Every run streams live activity to <AGY_MCP_STATE_DIR>/task_<id>.stream (default /tmp/agy-agent-mcp/tasks/task_<id>.stream).
The result is the sub-agent's summary, not its transcript; the transcript is on disk (.stream for humans, .ndjson for machines) and the result carries the paths.
You can watch any run live from a terminal with tail -f:
tail -f /tmp/agy-agent-mcp/tasks/task_<id>.streamSample transcript:
session open · cwd=/tmp/probe · permission_mode=request-review · tools=60
● user_input
● agent_response
⎿ done in 3.5s · 8059 tokens
← Write /tmp/probe/hello.txt
⎿ done in 1.2s
→ Read /tmp/probe/hello.txt
⎿ 1 lines, 6 bytes · done in 0.02s
● agent_response
Created /tmp/probe/hello.txt with the word probe.
⎿ done in 3.4s · 2198 tokens
== done: status=SUCCESS · 12.1sWhether the client shows live progress depends on the client (OpenCode does not, Claude Code does).
Call watch_task for an in-protocol view of the live step digest (steps, step_count, phase, usage_latest) and recent transcript lines.
npx agy-agent-follow --model gemini-3.8-flash --effort high "summarize the open TODOs in src/ in one paragraph"Delegates through the same runner as the MCP tools; every mirrored transcript line is printed to stdout as it is written, with the machine-readable result JSON right before exit (exit code 0 only on status: "success").
--tool general|explore switches the posture (accept-edits vs read-only plan), plus --cwd and --timeout-ms.
--effort low|medium|high sets the reasoning tier; a model ID that already carries one (e.g. gemini-3.8-flash-high) must not repeat a different tier — that combination is refused locally, before any task is spawned.
Ctrl-C / SIGTERM kill the in-flight agy child (receipts in the same tasks directory).
Symptom | Cause | What to do |
Refused call | Input argument validation failed before any child process was spawned. | Fix the argument named in the error message and call the tool again. |
Failed run | The sub-agent exited non-zero, timed out, or hit a quota ceiling. | Inspect |
Missing permission | A tool required user approval that headless execution cannot provide. | Pass |
Unknown model ID | The CLI does not recognize the ID, or it carries a tier that conflicts with an explicit |
|
Variable | Default | Purpose |
|
| Path to the Antigravity CLI binary. |
|
| Per-run idle timeout in ms (15 min, resets on child output; |
|
| Hard wall-clock timeout ceiling per run in ms ( |
| unset | Directory jail restricting allowed task |
|
| Directory for task |
|
| Days to retain task transcripts and receipts on startup sweep ( |
| unset | Set to |
npm test # offline test suite (test/client6.ts, fake agy binary)
node test/client.ts # maintainer live e2e test (requires agy auth + trusted workspace)
npm run lint # check formatting and lint rules with Biome
npm run lint:fix # auto-apply Biome formatting and safe fixesSee CONTRIBUTING.md for development setup (behavior lives in code and the test suite's summary lines).
MIT, see LICENSE.
Delegate read-only task to agy sub-agent (plan mode, read-only). Prompt must be self-contained. Blocks until finished, returning report (status, response, usage, files_touched, transcript paths). Default effort: low. background: true returns handle immediately (collect with watch_task). conversation_id resumes earlier thread. Headless runs auto-deny gated tools (in denied_actions; auto_approve skips).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Task cwd (defaults to server cwd). | |
| agent | No | Agent profile (see list_agents). | |
| model | No | Model (e.g. gemini-3.8-flash). Tier-carrying id (e.g. gemini-3.8-flash-high) encodes tier and wins over effort; pairing with different effort is refused locally. | |
| effort | No | Effort: low|medium|high (bare models; tier-carrying ids win). | |
| prompt | Yes | Self-contained task prompt for sub-agent. | |
| project | No | Project ID or name. | |
| sandbox | No | Terminal sandbox flag (--sandbox). | |
| add_dirs | No | Extra workspace dirs (--add-dir). | |
| background | No | Run in background; collect with watch_task. Emits no progress notifications. | |
| edit_scope | No | Allowed edit paths; out-of-scope edits flag in scope_violations. | |
| timeout_ms | No | Idle timeout in ms (0..3600000; 0 disables; default 900000). | |
| auto_approve | No | Pass --dangerously-skip-permissions to avoid auto-denying tools. Pair with sandbox. | |
| conversation_id | No | Existing conversation ID to resume. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present the description carries the full burden and does so: it discloses that the call blocks until completion, the exact result payload (status, response, usage, files_touched, transcript paths), the default effort, and that headless runs auto-deny gated tools with denied_actions recorded unless auto_approve is set. These are non-obvious runtime behaviors an agent could not infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and mode, then behavior, then parameter notes; nearly every clause carries information. The telegraphic style (e.g. 'in denied_actions; auto_approve skips') is dense and slightly elliptical, costing a bit of readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, no-annotation, no-output-schema tool, the description covers blocking semantics, return shape, background collection, and permission denial well. It says nothing about timeout behavior, failure modes, or what status values are possible, which are the remaining gaps for an agent planning recovery.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds value by stating the default effort is 'low' and explaining that conversation_id continues an earlier thread rather than starting fresh. It also ties background:true to watch_task, meaning not already conveyed by the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delegate read-only task to agy sub-agent') plus the execution mode ('plan mode, read-only'), which implicitly separates it from the sibling general_task. An agent can pick this tool for read-only exploration without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete operating guidance: prompt must be self-contained, background:true yields a handle to collect with watch_task, and conversation_id resumes a prior thread. It never explicitly contrasts with general_task or says when NOT to use this tool, so it stops short of a full routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delegate coding task to agy sub-agent (accept-edits mode, may edit files). Prompt must be self-contained. Blocks until finished, returning report (status, response, usage, files_touched, transcript paths). Default effort: medium. background: true returns handle immediately (collect with watch_task). conversation_id resumes earlier thread. Headless runs auto-deny gated tools (in denied_actions; auto_approve skips).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Task cwd (defaults to server cwd). | |
| agent | No | Agent profile (see list_agents). | |
| model | No | Model (e.g. gemini-3.8-flash). Tier-carrying id (e.g. gemini-3.8-flash-high) encodes tier and wins over effort; pairing with different effort is refused locally. | |
| effort | No | Effort: low|medium|high (bare models; tier-carrying ids win). | |
| prompt | Yes | Self-contained task prompt for sub-agent. | |
| project | No | Project ID or name. | |
| sandbox | No | Terminal sandbox flag (--sandbox). | |
| add_dirs | No | Extra workspace dirs (--add-dir). | |
| background | No | Run in background; collect with watch_task. Emits no progress notifications. | |
| edit_scope | No | Allowed edit paths; out-of-scope edits flag in scope_violations. | |
| timeout_ms | No | Idle timeout in ms (0..3600000; 0 disables; default 900000). | |
| auto_approve | No | Pass --dangerously-skip-permissions to avoid auto-denying tools. Pair with sandbox. | |
| conversation_id | No | Existing conversation ID to resume. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden, and it does substantial work: it discloses that the call blocks until completion, enumerates the report fields returned, states the default effort level, explains background-handle behavior, and warns that headless runs auto-deny gated tools listed in denied_actions. It stops short of covering failure modes, cost/latency implications of long blocking runs, or concurrency limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first clause and every subsequent sentence carries distinct operational information. The telegraphic, comma-spliced style packs a lot in but makes some clauses (headless auto-deny / auto_approve) harder to parse on first read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter delegation tool with no annotations and no output schema, the description is unusually complete: it explains blocking behavior, return payload fields, background retrieval via watch_task, thread resumption, permission denial in headless mode, and the edit-permission profile. Remaining gaps are sibling disambiguation against explore_task and guidance on timeout/sandbox interactions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter including background, conversation_id, auto_approve, and effort. The description adds only a couple of facts not in the schema, notably the medium default effort and the reinforced self-containment requirement for prompt, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: delegate a coding task to the agy sub-agent, with the key qualifier that it runs in accept-edits mode and may edit files. That edit capability implicitly separates it from explore_task, but the sibling is never named, so the distinction is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete operational context: the prompt must be self-contained, background: true returns a handle to collect with watch_task, and conversation_id resumes an earlier thread. What it lacks is an explicit rule for choosing between general_task and explore_task (read-only exploration), which is the most likely sibling confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List agent profiles for agent argument. Returns agents (raw agy agents output). Empty output means no custom agent configured.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It usefully discloses the return shape ('raw agy agents output') and the empty-result semantics, but omits whether built-in agents are included, ordering, or failure behavior. Read-only nature is only implied by 'List'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose and return semantics, with no filler. The terseness comes at some cost in clarity around what 'agy agents output' contains.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter read tool with no output schema, the description covers purpose, return format, and empty-result meaning. Only minor gaps remain, such as agent categorization and ordering, which are unlikely to block correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline of 4 applies. The description does add value by connecting the tool output to the 'agent' argument of other tools, which the empty schema cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List agent profiles') and ties it to a concrete consumer ('for agent argument'), which makes the purpose actionable. It is reasonably distinguishable from list_models, though the domain jargon 'agy agents' is unexplained and the tie to siblings is only implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the agent must infer that this is called to discover valid values for the 'agent' argument. The note that empty output means no custom agent configured is a useful usage signal, but there is no explicit when-to-use/when-not guidance or naming of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List models for model argument. Returns models (raw agy models output) and model_ids (parsed ids). CLI lists tier-carrying ids only; bare ids like gemini-3.8-flash are valid for model but not in list.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses return values (models raw output, model_ids parsed ids) and a key behavioral caveat: the CLI lists only tier-carrying ids, while bare ids are valid but omitted. It does not explicitly state read-only safety, but the nature of a list operation is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the purpose, then return details and a crucial caveat. Every sentence adds value without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, annotation-free tool with no output schema, the description explains the action, return values, and an important limitation. Nothing essential for an agent to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema baseline is 4. The description references a 'model argument' but that is not a parameter of this tool; no additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (List) and resource (models) and contextualizes it for the model argument. It does not explicitly differentiate from sibling tools like list_agents, but the resource is distinct enough for an agent to identify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use this to find models for the model argument, and explains that the returned list may not include all valid bare ids. No explicit when-not or alternatives are given, but the intended usage is implicit and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read transcript tail of an agy run (snapshot, not follow; no args = latest run). Digest: steps (50 most recent), step_count (total; step_count > steps.length means clipped), phase, elapsed_seconds, usage_latest, content (raw tail). Finished runs carry complete final result (failed run says why). wait: true blocks until finished in one call (not combinable with cancel; cannot await foreign run). cancel: true stops owned run (foreign/ambiguous reported ignored with hint).
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Block until finished and return result in one call. Incompatible with cancel; cannot await foreign run. | |
| cancel | No | Stop running task owned by this process and report cancelled. | |
| tail_lines | No | Trailing lines (1..2000, default 400; 0 returns all, capped at 200k chars). | |
| stream_file | No | Transcript or task ID. Omit for latest run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses snapshot semantics, digest contents including clipping behavior, final-result availability for finished runs, blocking behavior for wait, and ownership rules for cancel. It also notes that foreign/ambiguous cancel requests are ignored with a hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Information is front-loaded with the core purpose first, then digest contents, then wait/cancel behavior. The dense single paragraph is efficient and every sentence adds value, though the density slightly reduces scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description fully explains the return digest (steps, step_count with clipping indicator, phase, elapsed_seconds, usage_latest, content). It covers everything an agent needs to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all four parameters. The description adds a few useful details (no args means latest run, wait/cancel interaction, tail digest meaning) but does not meaningfully extend parameter semantics beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read) and resource (transcript tail of an agy run), with scope details like snapshot-not-follow and no-args-latest. An agent can distinguish it from list_agents or general_task without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains key usage conditions: omit args for latest run, use wait:true to block until finished, cancel:true to stop owned runs, and notes incompatibility between wait and cancel. It lacks explicit routing against siblings, but gives clear operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0explore_task15 fields changedInput schema / properties / add_dirs / descriptionPrevious value: -"Extra directories to add to the task's workspace (--add-dir, repeatable)"New value: +"Extra workspace dirs (--add-dir)."Input schema / properties / agent / descriptionPrevious value: -"Antigravity agent profile to use (see list_agents)"New value: +"Agent profile (see list_agents)."Input schema / properties / auto_approve / descriptionPrevious value: -"Expert switch: pass --dangerously-skip-permissions so headless runs stop auto-denying gated tools. Pair it with sandbox when granting it. Allowed by this server."New value: +"Pass --dangerously-skip-permissions to avoid auto-denying tools. Pair with sandbox."Input schema / properties / backgroundAdded value: +{
+ "description": "Run in background; collect with watch_task. Emits no progress notifications.",
+ "type": "boolean"
+}Input schema / properties / conversation_id / descriptionPrevious value: -"Existing agy conversation ID to continue/resume instead of starting a new conversation. Returned by previous task results."New value: +"Existing conversation ID to resume."Input schema / properties / cwd / descriptionPrevious value: -"Working directory for the delegated task (project the sub-agent operates on). Defaults to the server's cwd."New value: +"Task cwd (defaults to server cwd)."Input schema / properties / edit_scope / descriptionPrevious value: -"Give the sub-agent an edit boundary (files and directories relative to cwd, or absolute). Out-of-scope changes are surfaced in the result's files_touched/scope_violations audit; it is an audit-and-replay control, not a sandbox — the CLI writes files itself."New value: +"Allowed edit paths; out-of-scope edits flag in scope_violations."Input schema / properties / effort / descriptionPrevious value: -"Reasoning effort for the task"New value: +"Effort: low|medium|high (bare models; tier-carrying ids win)."Input schema / properties / effort / enumPrevious value: -[
- "low",
- "medium",
- "high",
- "xhigh",
- "max"
-]New value: +[
+ "low",
+ "medium",
+ "high"
+]Input schema / properties / model / descriptionPrevious value: -"Model for the task, e.g. gemini-3.8-flash-medium, claude-opus-5-5-high (see list_models)"New value: +"Model (e.g. gemini-3.8-flash). Tier-carrying id (e.g. gemini-3.8-flash-high) encodes tier and wins over effort; pairing with different effort is refused locally."Input schema / properties / project / descriptionPrevious value: -"Antigravity project ID or name for the task"New value: +"Project ID or name."Input schema / properties / prompt / descriptionPrevious value: -"Full, self-contained task description for the sub-agent. Include all needed context and file paths."New value: +"Self-contained task prompt for sub-agent."Input schema / properties / prompt / patternAdded value: +"\\S"Input schema / properties / sandbox / descriptionPrevious value: -"Run the task with Antigravity's terminal sandbox flag enabled (--sandbox)"New value: +"Terminal sandbox flag (--sandbox)."Input schema / properties / timeout_ms / descriptionPrevious value: -"Idle timeout for the run in ms (0..3600000; 0 disables the idle kill for this run). Resets on every stdout/stderr chunk from the child; kicks in after this much child silence and kills the child (SIGTERM, then SIGKILL after 5s). Default: 900000 (AGY_MCP_IDLE_TIMEOUT_MS)."New value: +"Idle timeout in ms (0..3600000; 0 disables; default 900000)."general_task15 fields changedInput schema / properties / add_dirs / descriptionPrevious value: -"Extra directories to add to the task's workspace (--add-dir, repeatable)"New value: +"Extra workspace dirs (--add-dir)."Input schema / properties / agent / descriptionPrevious value: -"Antigravity agent profile to use (see list_agents)"New value: +"Agent profile (see list_agents)."Input schema / properties / auto_approve / descriptionPrevious value: -"Expert switch: pass --dangerously-skip-permissions so headless runs stop auto-denying gated tools. Pair it with sandbox when granting it. Allowed by this server."New value: +"Pass --dangerously-skip-permissions to avoid auto-denying tools. Pair with sandbox."Input schema / properties / backgroundAdded value: +{
+ "description": "Run in background; collect with watch_task. Emits no progress notifications.",
+ "type": "boolean"
+}Input schema / properties / conversation_id / descriptionPrevious value: -"Existing agy conversation ID to continue/resume instead of starting a new conversation. Returned by previous task results."New value: +"Existing conversation ID to resume."Input schema / properties / cwd / descriptionPrevious value: -"Working directory for the delegated task (project the sub-agent operates on). Defaults to the server's cwd."New value: +"Task cwd (defaults to server cwd)."Input schema / properties / edit_scope / descriptionPrevious value: -"Give the sub-agent an edit boundary (files and directories relative to cwd, or absolute). Out-of-scope changes are surfaced in the result's files_touched/scope_violations audit; it is an audit-and-replay control, not a sandbox — the CLI writes files itself."New value: +"Allowed edit paths; out-of-scope edits flag in scope_violations."Input schema / properties / effort / descriptionPrevious value: -"Reasoning effort for the task"New value: +"Effort: low|medium|high (bare models; tier-carrying ids win)."Input schema / properties / effort / enumPrevious value: -[
- "low",
- "medium",
- "high",
- "xhigh",
- "max"
-]New value: +[
+ "low",
+ "medium",
+ "high"
+]Input schema / properties / model / descriptionPrevious value: -"Model for the task, e.g. gemini-3.8-flash-medium, claude-opus-5-5-high (see list_models)"New value: +"Model (e.g. gemini-3.8-flash). Tier-carrying id (e.g. gemini-3.8-flash-high) encodes tier and wins over effort; pairing with different effort is refused locally."Input schema / properties / project / descriptionPrevious value: -"Antigravity project ID or name for the task"New value: +"Project ID or name."Input schema / properties / prompt / descriptionPrevious value: -"Full, self-contained task description for the sub-agent. Include all needed context and file paths."New value: +"Self-contained task prompt for sub-agent."Input schema / properties / prompt / patternAdded value: +"\\S"Input schema / properties / sandbox / descriptionPrevious value: -"Run the task with Antigravity's terminal sandbox flag enabled (--sandbox)"New value: +"Terminal sandbox flag (--sandbox)."Input schema / properties / timeout_ms / descriptionPrevious value: -"Idle timeout for the run in ms (0..3600000; 0 disables the idle kill for this run). Resets on every stdout/stderr chunk from the child; kicks in after this much child silence and kills the child (SIGTERM, then SIGKILL after 5s). Default: 900000 (AGY_MCP_IDLE_TIMEOUT_MS)."New value: +"Idle timeout in ms (0..3600000; 0 disables; default 900000)."list_agents1 field changedInput schema / additionalPropertiesAdded value: +falselist_models1 field changedInput schema / additionalPropertiesAdded value: +falsewatch_task4 fields changedInput schema / properties / cancelAdded value: +{
+ "description": "Stop running task owned by this process and report cancelled.",
+ "type": "boolean"
+}Input schema / properties / stream_file / descriptionPrevious value: -"Stream transcript to read. Omit for the latest task_<id>.stream in AGY_MCP_STATE_DIR. Accepted forms: an absolute path under AGY_MCP_STATE_DIR, a bare file name like \"task_f8870173.stream\", or a task id like \"task_f8870173\" / \"f8870173\"."New value: +"Transcript or task ID. Omit for latest run."Input schema / properties / tail_lines / descriptionPrevious value: -"Number of trailing lines to return (1..2000, default 400; 0 returns the full transcript, hard-capped at 200,000 chars)."New value: +"Trailing lines (1..2000, default 400; 0 returns all, capped at 200k chars)."Input schema / properties / waitAdded value: +{
+ "description": "Block until finished and return result in one call. Incompatible with cancel; cannot await foreign run.",
+ "type": "boolean"
+}v0.2.1explore_taskgeneral_tasklist_agentslist_modelswatch_taskScored across 5 tools
Each tool targets a clearly distinct action: launching write-capable tasks (general_task), read-only tasks (explore_task), monitoring runs (watch_task), and enumerating models/agents. The two task tools are separated by mode (accept-edits vs plan) and the descriptions make the boundary explicit. No tool pair is likely to be misselected.
Names are readable and follow a loose grouping convention: task-oriented tools end in `_task` while enumeration tools use `list_` prefix. This is not a single strict verb_noun pattern throughout, but the deviation is minor and predictable rather than chaotic.
Five tools is well-scoped for a sub-agent delegation server: two launch modes, one monitor/control tool, and two discovery tools. Cancel and wait are folded into watch_task rather than becoming separate tools, which keeps the surface lean without losing capability.
The core lifecycle is covered: launch (two modes), monitor/wait/cancel, resume via conversation_id, and enumerate models/agents. Minor gaps exist — there is no tool to list all runs (watch_task with no args only resolves the latest) and foreign runs cannot be awaited — but agents can work around these.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Hosted coding agent: start, follow up on and stop tasks that can open GitHub pull requests.
Run and manage AI agent tasks on tavya: create, search and steer tasks, read wikis, call the API.
Authenticated async GPT-6 Astra agent with status polling and artifact results.
