# agy-bridge MCP server

> Delegates heavy computational tasks from Claude Code to the Antigravity CLI with automated model routing and quota-aware failover.

- Repository: https://github.com/sshahzaiib/agy-bridge
- Page: https://hostedmcp.org/servers/sshahzaiib/agy-bridge
- Transport: stdio
- Stars: 67
- License: MIT
- Latest version: 0.3.1

## Install

### Claude Code

```sh
claude mcp add agy-bridge -- npx -y agy-bridge
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "agy-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "agy-bridge"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "agy-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "agy-bridge"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"agy-bridge","type":"stdio","command":"npx","args":["-y","agy-bridge"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "agy-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "agy-bridge"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add agy-bridge -- npx -y agy-bridge
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.agy-bridge]
command = "npx"
args = ["-y", "agy-bridge"]
```

### Gemini CLI

```sh
gemini mcp add -s user agy-bridge npx -- -y agy-bridge
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "agy-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "agy-bridge"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `AGY_DEFAULT_MODEL` | no | no | Fallback model when no chain entry is available |
| `AGY_MAX_OUTPUT_CHARS` | no | no | Truncation cap for tool output, in characters (default 50000) |
| `AGY_ON_FAILURE` | no | no | Set to `strict` to instruct the calling agent not to absorb failed delegations (default `fallback`) |
| `AGY_PATH` | no | no | Path to the agy binary (defaults to `agy` on PATH) |
| `AGY_TIMEOUT` | no | no | Override the per-tool timeouts, in seconds |

## Tools (6)

- `analyze_files`: Delegate file analysis to the Antigravity CLI (Gemini) instead of reading files yourself. USE THIS whenever a file is large (>200 lines) or the task spans more than 3 files: logs, database dumps, generated code, cross-file reviews, comparisons. The files never enter your context — only the answer does.
- `deep_search`: Delegate codebase archaeology to the Antigravity CLI: git log/diff/blame spelunking, wide greps across a repo, 'when/why did X change', 'where is Y used'. USE THIS instead of running many search commands yourself — it saves your context.
- `web_lookup`: Delegate a web/documentation lookup to the Antigravity CLI (Gemini with web access): library docs, API references, error messages, current versions, external knowledge. USE THIS when you need information you don't have or that may be newer than your training data.
- `adversarial_review`: Get an adversarial second opinion from a different model family (Gemini Pro). ALWAYS use this for plan critiques, design reviews, and pre-merge code review: it hunts for flaws, edge cases, security issues, and unstated assumptions you may have missed.
- `follow_up`: Continue a previous Antigravity session by session_id (returned by every other tool). USE THIS for follow-up questions about a prior delegation — the full prior context is already on agy's side, so you don't resend anything.
- `delegate`: Raw delegation to the Antigravity CLI for heavy tasks that don't fit the other tools. agy has full tool access (shell, file reads, web) in the given cwd.

## FAQ

### What does agy-bridge do for Claude Code?

It allows Claude Code to delegate heavy tasks like large file analysis, deep git searches, and web lookups to the Antigravity CLI, saving Claude's context window and tokens.

### How does the bridge handle model quota exhaustion?

The bridge monitors for 429 resource exhausted errors, parses the reset time, and automatically retries the prompt using the next available model in the tool's routing chain.
