# agy-mcp

[日本語](README.ja.md) · [Apache-2.0](LICENSE)

`agy-mcp` is a local [Model Context Protocol](https://modelcontextprotocol.io/) server that lets an MCP client delegate a task to the Google Antigravity CLI (`agy`). It uses stdio, starts `agy` as a child process, and returns the CLI result as structured MCP content.

It is designed for a personal local installation that can also be inspected, adapted, and contributed to as open source. It is not an Antigravity product and does not replace Antigravity's own access controls or account requirements.

## What it provides

| MCP tool               | Purpose                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `antigravity_run`      | Starts a new Antigravity conversation and returns its result and, when supplied by the CLI, its `conversation_id`. |
| `antigravity_continue` | Continues a conversation by ID. Without an ID, it asks `agy` to continue its latest conversation.                  |
| `antigravity_models`   | Runs `agy models` and returns the CLI output. It does not start a model turn, but it may contact Antigravity.      |

`run` and `continue` accept a prompt, an absolute workspace, optional model and effort, a mode (`plan` or `accept-edits`), an autonomy level, and a hard timeout. The server runs up to four `agy` commands concurrently by default. Set `AGY_MCP_MAX_CONCURRENT` to change this limit.

List model slugs with `antigravity_models`, then use one in `model`.

```json
{
  "prompt": "Review the authentication flow and identify likely edge cases.",
  "workspace": "/absolute/path/to/workspace",
  "model": "a-slug-returned-by-antigravity_models",
  "mode": "plan",
  "autonomy": "safe",
  "timeout_seconds": 300
}
```

`timeout_seconds` defaults to 300 and accepts integers from 10 through 3600.

## Parallel calls

Submit multiple MCP tool calls concurrently to run independent tasks in parallel. Each call has its own CLI process, output, progress, timeout, and cancellation. Canceling one call leaves the others running; shutting down the server stops all active calls.

- New conversations and continuations with different explicit `conversation_id` values can overlap, including in the same workspace.
- Two continuations specifying the same conversation ID cannot overlap, even across workspaces; the second returns `BUSY`.
- A continuation without an ID (`--continue`) requires exclusive access to the server. It returns `BUSY` while any call is active, and other calls return `BUSY` while it runs. Use the ID returned by `antigravity_run` for parallel follow-ups.
- All commands, including `antigravity_models`, count toward the concurrency limit. Calls exceeding the limit return `BUSY` immediately and are not queued. Set the limit to `1` to restore serial execution.

These limits and conversation locks apply within one server process. Workspace files, CLI state, credentials, and account quota remain shared; the bridge does not create isolated worktrees or coordinate other servers or CLI sessions. Assign separate files or worktrees when parallel tasks edit code, and prefer explicit conversation IDs because other sessions can change the latest conversation.

## Requirements

- Node.js 22 or newer
- pnpm 10 or newer (the repository pins pnpm 10.18.1)
- An installed, authenticated Antigravity CLI available as `agy`, or an executable path supplied through `AGY_MCP_BIN`
- A workspace that Antigravity is allowed to use

Read the [Antigravity CLI headless documentation](https://antigravity.google/docs/cli/headless/) for the CLI's installation, authentication, trust, permissions, and current behavior. This project uses the [official TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk).

## Install from source

```bash
git clone https://github.com/Kaikei-e/agy-mcp.git
cd agy-mcp
pnpm install --frozen-lockfile
pnpm build
pnpm run doctor
```

`pnpm run doctor` checks the configured workspace and verifies that the installed `agy` advertises the CLI flags this bridge needs. It does not start a model turn. Authentication and workspace trust must still be established with Antigravity itself.

For an optional live smoke test after authenticating `agy`:

```bash
pnpm run probe
```

The probe invokes `run` and then `continue` on the returned conversation. It can consume your Antigravity quota and create a conversation. It is deliberately not part of CI.

## Connect an MCP client

Build the server, then configure the client to launch the compiled entry point. The examples below show the client-specific configuration; replace every absolute path with your own.

For Claude Code, a project `.mcp.json` entry can look like this:

```json
{
  "mcpServers": {
    "antigravity": {
      "command": "node",
      "args": ["/absolute/path/to/agy-mcp/dist/index.js"],
      "env": {
        "AGY_MCP_DEFAULT_WORKSPACE": "/absolute/path/to/workspace",
        "AGY_MCP_ALLOWED_ROOT": "/absolute/path/to",
        "AGY_MCP_MAX_CONCURRENT": "4"
      }
    }
  }
}
```

For Codex CLI or the Codex IDE, add an equivalent stdio server to `~/.codex/config.toml`, or to `.codex/config.toml` in a trusted project. Codex CLI and the IDE share this configuration; see the [Codex MCP configuration documentation](https://developers.openai.com/codex/mcp/) for the supported settings. Copy [examples/codex.config.toml](examples/codex.config.toml), replace every placeholder with an absolute path, and merge the relevant tables into the existing file. Edit an existing `mcp_servers.antigravity` entry instead of adding a duplicate table, and do not overwrite other settings.

```toml
[mcp_servers.antigravity]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/agy-mcp/dist/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 3660

[mcp_servers.antigravity.env]
AGY_MCP_DEFAULT_WORKSPACE = "/absolute/path/to/workspace"
AGY_MCP_ALLOWED_ROOT = "/absolute/path/to"
AGY_MCP_MAX_CONCURRENT = "4"
# Set this when `agy` is not available in Codex's PATH.
AGY_MCP_BIN = "/absolute/path/to/agy"
```

`command = "node"` also works when Codex inherits a PATH containing Node. An absolute Node path is more reliable for GUI or IDE launches; find it with `command -v node`. Set `AGY_MCP_BIN` to an absolute executable path when `agy` is not on that PATH (`command -v agy`). Remove that entry when the `agy` command is available normally. Codex defaults to a 60-second tool timeout and a 10-second startup timeout. This server defaults each request to 300 seconds and accepts up to 3600; `tool_timeout_sec = 3660` leaves a 60-second client margin above the maximum, while `startup_timeout_sec = 20` allows more startup time.

Instead of editing TOML first, `codex mcp add` can register the stdio command:

```bash
codex mcp add antigravity \
  --env "AGY_MCP_DEFAULT_WORKSPACE=/absolute/path/to/workspace" \
  --env "AGY_MCP_ALLOWED_ROOT=/absolute/path/to" \
  --env "AGY_MCP_MAX_CONCURRENT=4" \
  --env "AGY_MCP_BIN=/absolute/path/to/agy" \
  -- "/absolute/path/to/node" "/absolute/path/to/agy-mcp/dist/index.js"
codex mcp list
codex mcp get antigravity
```

The `add` command does not set `startup_timeout_sec` or `tool_timeout_sec`. After using it, add those timeout settings to the generated server entry, preserving any other configuration. Restart the Codex CLI or IDE session after changing MCP configuration. The project-level file is loaded only for a trusted project.

The server communicates over standard input and output. Do not wrap it in a command that writes diagnostic text to stdout. Configure the MCP client's own timeout slightly longer than the tool's `timeout_seconds`; progress notifications and heartbeats are useful status signals, but they do not guarantee that a client resets its timeout.

If Codex reports that it cannot start the server, check the absolute Node path and `AGY_MCP_BIN`; shell startup files are not always loaded by IDE processes. If a call times out, check both the request's `timeout_seconds` (10–3600) and `tool_timeout_sec`, then restart Codex after editing the config.

## Safety and workspace boundaries

The default request settings are `mode: "plan"` and `autonomy: "safe"`.

- `safe` inherits the permissions and workspace trust decisions made by `agy`. It is not a read-only guarantee.
- `sandbox` adds the CLI's terminal restrictions. Its scope and behavior are defined by Antigravity.
- `full` passes the CLI permission-bypass flag. It is rejected unless the server environment explicitly sets `AGY_MCP_ALLOW_FULL_AUTONOMY=true`.

Every supplied `workspace` must be an absolute, accessible directory. The server canonicalizes it before use. `AGY_MCP_ALLOWED_ROOT`, when set, permits only canonical workspaces beneath that root. This limits the selected workspace; it does **not** sandbox a child process's filesystem access or network access. Only point the server at workspaces and permissions you trust.

The bridge disables CLI slash-command expansion for prompts, but output returned by an agent remains untrusted data. Review proposed commands and edits before acting on them.

## Configuration

| Variable                      | Default                  | Meaning                                                                                      |
| ----------------------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| `AGY_MCP_BIN`                 | `agy`                    | CLI executable name, or an absolute path or path relative to the server's current directory. |
| `AGY_MCP_DEFAULT_WORKSPACE`   | server current directory | Default workspace after resolution and canonicalization.                                     |
| `AGY_MCP_ALLOWED_ROOT`        | unset                    | Optional canonical root that must contain every chosen workspace.                            |
| `AGY_MCP_MAX_CONCURRENT`      | `4`                      | Maximum simultaneous CLI processes per server; integer from 1 to 32.                         |
| `AGY_MCP_MAX_OUTPUT_CHARS`    | `40000`                  | Maximum characters in each MCP result representation; integer from 1024 to 1000000.          |
| `AGY_MCP_MAX_BUFFER_BYTES`    | `8388608`                | Maximum captured CLI stdout before the process is stopped; integer from 1024 to 67108864.    |
| `AGY_MCP_ALLOW_FULL_AUTONOMY` | `false`                  | Set exactly `true` to allow requests with `autonomy: "full"`.                                |

Each tool response supplies `structuredContent` and the same JSON in its text content. The whole representation, including error and metadata fields, is capped by `AGY_MCP_MAX_OUTPUT_CHARS`; truncated results say so. CLI stdout is independently capped by `AGY_MCP_MAX_BUFFER_BYTES` per process, so total memory use grows with concurrency.

Long-running calls emit MCP progress metadata when the client provides a progress token, plus a heartbeat while the CLI is waiting. On cancellation, timeout, or output-limit failure, the server attempts to terminate the CLI process group on Linux and macOS. Windows termination is best effort; verify that no child process remains when that matters.

## Development

```bash
pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm format:check
```

`pnpm pack` runs the package's `prepack` build before creating an archive. There is no automated npm publishing workflow.

See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before filing an issue or pull request. Changes are released under the [Apache License 2.0](LICENSE).