Antigravity CLI (agy) MCP server not connecting: the fixes

Start with /mcp

Type /mcp in the prompt and press Enter to open the MCP manager. It shows each server as active, disconnected or loading, with the error for one that failed, and lets you reload the config files after an edit and read the server's connection log. Servers are grouped by where they came from, so a plugin's server is listed under that plugin.

Update agy before digging further. Since v1.4.1, a server whose process exits is marked Error; before that it kept showing Ready while calls failed with client is closing: EOF. v1.3.1 fixed a restart from /mcp that could leave the server stopped. --log-file sets where the CLI writes its own log.

Which file agy reads

• Global servers live in ~/.gemini/config/mcp_config.json and apply to every project. Workspace servers live in <workspace>/.agents/mcp_config.json and apply to that workspace only. Enabled plugins add their own servers from the plugin's mcp.json.
• agy doesn't read MCP servers from ~/.gemini/settings.json or a project's .gemini/settings.json, where Gemini CLI kept them. Its own ~/.gemini/antigravity-cli/settings.json holds CLI settings and permission rules, not servers.
• Both files use an mcpServers object. Each entry needs one transport: command for a local stdio server or serverUrl for a remote one.
• "disabled": true keeps an entry without connecting it. enabledTools shows only the tools it names, so a typo there hides every tool on the server; disabledTools hides the ones it lists.

{
  "mcpServers": {
    "my-remote": {
      "serverUrl": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    },
    "my-local": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "API_KEY": "YOUR_API_KEY" }
    }
  }
}

Configs carried over from Gemini CLI

• On first launch, agy offers a checklist of Gemini CLI settings to convert. If you move a server by hand, rename httpUrl (or Gemini's url) to serverUrl. agy also accepts url, but httpUrl isn't supported.
• Remote servers must use Streamable HTTP. The older HTTP+SSE transport isn't supported, so a server that only offers an SSE endpoint, often a URL ending in /sse, won't connect under any field name. Use the provider's Streamable HTTP URL, or run its stdio version instead.
• Gemini CLI's trust, includeTools and excludeTools fields aren't in agy's list of server properties. Use enabledTools or disabledTools in the entry, and permission rules for approvals.
• Gemini extensions convert with agy plugin import gemini. Workspace skills move from .gemini/skills/ to .agents/skills/; GEMINI.md and AGENTS.md files keep working as they are.

${VAR} in headers is sent as written

Gemini CLI and Claude Code replace ${VAR} with the variable's value. agy doesn't do that in mcp_config.json. Issue #233 on the Antigravity CLI repo, open since May 29, 2026, shows stdio servers receiving "${S1_BASE_URL}" as a literal value, and a later comment shows a remote server answering "calling initialize: sending initialize: Unauthorized" because the header went out as Bearer ${GITHUB_MCP_PAT}. The variable being set in your shell makes no difference.

• The v1.4.0 changelog entry about header variables applies to plugin MCP servers and the values you configure for them, not to mcp_config.json.
• To make a server connect today, write the value into the file. Use the global ~/.gemini/config/mcp_config.json for anything secret, not a workspace file you might commit.
• To keep the secret out of the file, run the server over stdio with a command that reads the secret itself, such as a wrapper script or a local bridge that adds the header.

Sign-in, timeouts and approvals

• agy handles OAuth for servers that support dynamic client registration with no extra config. For a server without it, add oauth with clientId (and clientSecret) and register https://antigravity.google/oauth-callback as a redirect URI with the provider. Tokens are kept in ~/.gemini/antigravity/mcp_oauth_tokens.json.
• Google Cloud servers can use "authProviderType": "google_credentials", which needs Application Default Credentials from gcloud auth application-default login.
• agy waits 5 minutes for a server to connect and list its tools and 3 minutes per tool call. timeoutSeconds replaces both limits, so a small value can stop a slow server from connecting at all.
• Unconfigured MCP tools run in Ask mode. A rule like mcp(server/*) under permissions.allow in ~/.gemini/antigravity-cli/settings.json lets every tool on that server run without a prompt.

Taskhold-specific checks

Taskhold is a remote Streamable HTTP server at https://taskhold.com/api/mcp, so agy connects to it directly. When the taskhold tools don't work in agy, check these in order:

1. The entry is under mcpServers in ~/.gemini/config/mcp_config.json with serverUrl set to exactly https://taskhold.com/api/mcp. The www host redirects and the redirect drops the Authorization header. A setup URL from Settings, pasted into agy with "set this up", writes the entry for you.
2. The header is Authorization: Bearer followed by the key itself, which starts with atd_sk_. Taskhold's 401 names the cause: missing_key, bad_header, not_a_taskhold_key or unknown_key. not_a_taskhold_key with a header like Bearer ${TASKHOLD_API_KEY} is the unexpanded variable from the section above.
3. Sign-in without a key (OAuth) is set up for Claude Code, Cursor, Codex, claude.ai and ChatGPT. agy sends the key in the header. With no header, /mcp can list taskhold and its tools, but every call comes back 401 missing_key.
4. A 402 means the key works but the trial ended or the plan was canceled. Restart the plan and the same config works again.
5. Add mcp(taskhold/*) to permissions.allow so progress reports don't stop on a prompt. Settings in Taskhold shows Connected after the first call.

To keep the key out of mcp_config.json, the Antigravity CLI page shows Taskhold's stdio build, which reads TASKHOLD_API_KEY or ~/.taskhold/config.json on its own, along with the AGENTS.md snippet that puts every task, step and question on the live board. The same checks for other clients: Gemini CLI, OpenCode and Codex CLI.