Agy Bridge

What sshahzaiib/agy-bridge MCP server does

The sshahzaiib/agy-bridge MCP server lets an MCP client send demanding development tasks to the Antigravity CLI (agy) instead of processing all source material in the client context. The bridge returns the delegated answer, while large files, repository searches, and web lookup content remain on the agy side during the request.

Its six tools divide common tasks by intent:

• analyze_files handles large files, logs, database dumps, generated code, and reviews spanning multiple files.
• deep_search investigates git history, diffs, blame data, repository-wide references, and why or where code changed.
• web_lookup requests documentation, API references, error explanations, current versions, or other external information.
• adversarial_review asks a different model family to look for flaws, security issues, edge cases, and hidden assumptions in plans or code.
• follow_up continues an earlier session using its session_id.
• delegate provides a general route for heavy tasks that do not match the specialized tools.

How it works

Each request can include an optional project directory through cwd and an optional exact model name. On its first use, the bridge queries agy models, caches the available models for the process lifetime, and selects the first available model in the relevant preference chain. If those choices are unavailable, it falls back to AGY_DEFAULT_MODEL and then to agy's own default.

The sshahzaiib/agy-bridge MCP server validates requested model names before execution. It also watches agy log output for quota exhaustion. When a model reports a 429 resource error, the bridge stops the process, records the reset period, and retries with the next eligible model. Responses include the selected model and session identifier, and may include failover details.

Sessions support multi-turn work without resending the original context. The follow_up tool uses the returned session identifier to continue the earlier Antigravity conversation.

Setup and configuration

The documented setup requires Node.js 18 or newer, an installed and authenticated Antigravity CLI, and Claude Code. Register the npm package as an MCP server with:

claude mcp add-json -s user agy-bridge '{"command":"npx","args":["-y","agy-bridge"],"timeout":600000}'

The repository also provides a CLAUDE.md file containing delegation rules that can be downloaded into a project or used globally. The client-side timeout in the example is separate from agy's execution timeout; clients with shorter deadlines can stop waiting before agy finishes.

By default, tool budgets are 120 seconds for web lookups, 180 seconds for deep searches, 300 seconds for file analysis, adversarial reviews, and follow-ups, and 600 seconds for general delegation. AGY_TIMEOUT changes the common budget, while variables such as AGY_TIMEOUT_DEEP_SEARCH override an individual tool. The per-tool setting takes precedence.

Tools and capabilities

The bridge supports model failover, cooldown tracking after quota exhaustion, configurable output truncation, optional agy sandbox mode, and process-group cancellation. Cancelling an MCP call also terminates the agy run rather than leaving helper processes behind. The agy-bridge process can use Gemini, Claude, or GPT-OSS models when those models are available through the authenticated Antigravity CLI and match the routing rules.

Limitations and notes

The Antigravity CLI must already be installed and authenticated; the bridge does not replace that prerequisite. Client and agy timeouts must be aligned for long-running requests. If the client deadline expires first, the session can still be continued with follow_up using the returned session identifier. Model availability and quota status depend on the configured agy account and currently available models.