How to Add a Remote MCP Server to Gemini CLI

How do I add a remote MCP server to Gemini CLI?

Run gemini mcp add --transport http <name> <url> -s user, then /mcp auth <name> inside the CLI and approve in the browser. If you edit ~/.gemini/settings.json by hand instead, the field must be httpUrl, not url — and it fails in a way that looks like a broken server rather than a wrong key.

Check availability first

On June 18, 2026, Gemini CLI stopped serving requests for consumer Google accounts — free, Google AI Pro, and Ultra. It continues to work with:

• Gemini Code Assist Standard or Enterprise licenses
• Paid Gemini API keys, including Gemini Enterprise Agent Platform keys

Google has announced that Antigravity CLI is the path forward for consumers, but has not announced an end-of-life date for Gemini CLI on those paid and enterprise tiers, and it is still shipping releases.

Worth knowing because it wastes real time: Google's own gemini-cli README still advertises a free tier for personal Google accounts. That line predates the June 18 change, and the announcement supersedes it. If requests aren't being served on a personal account, that is why — not your MCP config.

Adding the server

The fastest path is one command:

gemini mcp add --transport http my-server https://mcp.example.com/mcp -s user

Include -s user deliberately. It writes the entry to your user-level ~/.gemini/settings.json, making it available in every project. Without -s, Gemini CLI defaults to project scope and the entry applies only to the directory you ran the command in — which produces a server that mysteriously exists in one repo and not another.

To edit the file directly, add this to ~/.gemini/settings.json, or to a project's .gemini/settings.json for one workspace:

{
  "mcpServers": {
    "my-server": {
      "httpUrl": "https://mcp.example.com/mcp",
      "oauth": { "enabled": true }
    }
  }
}

httpUrl, not url

In Gemini CLI, url means an SSE server. httpUrl is the Streamable HTTP transport that hosted MCP servers actually use.

This is worth stating plainly because of how it presents. url selects the SSE transport and httpUrl selects Streamable HTTP, so the entry is accepted and the transport simply mismatches. Gemini CLI is also deliberately quiet about it: connection errors for background servers are silent by default, and startup shows only a single hint — "MCP issues detected. Run /mcp list for status." So run /mcp list before re-checking your URL or your account; the field name is the thing to look at.

The "oauth": {"enabled": true} block is optional, but it makes the auth expectation explicit.

Qwen Code, which is built on the Gemini CLI lineage, shares this exact quirk.

Authorization

Start Gemini CLI and run:

/mcp auth my-server

A browser tab opens to the server's consent screen. Sign in and approve. Tokens are stored in ~/.gemini/mcp-oauth-tokens.json.

Run /mcp to check server status at any point.

Gemini Code Assist

The Gemini Code Assist VS Code extension's agent mode reads the same ~/.gemini/settings.json (Standard and Enterprise editions), so the config above carries over with no extra steps.

If the OAuth flow won't complete inside the IDE, run the authorization once in Gemini CLI — settings and tokens are shared, so the extension inherits the authenticated server.

What usually goes wrong

• Connects but tools fail, or auth never triggers. url instead of httpUrl. Fix the field, then re-run /mcp auth.
• Requests aren't served on a personal Google account. The June 18, 2026 consumer retirement. Not a config problem.
• The server exists in one project but not another. The entry was written at project scope. Re-add with -s user.
• "Unauthorized" or stale-token errors. Run /mcp auth <name> again. Tokens live in ~/.gemini/mcp-oauth-tokens.json.
• Connection fails immediately. Check the URL against exactly what the server publishes, including the path and any trailing slash.

Moving to Antigravity CLI?

Antigravity's CLI (the agy command) reads a different file — ~/.gemini/config/mcp_config.json — and uses serverUrl rather than httpUrl, so a Gemini CLI entry does not carry over as-is. Antigravity offers to migrate legacy config on first launch — that onboarding pass is what picks up a server you added with gemini mcp add, since it covers global configurations. agy plugin import gemini is narrower: it converts legacy extensions into Antigravity plugins, so it will not do anything for a plain mcpServers entry. Verify the result rather than assuming.

A worked example

With a real server — Tempreon, a hosted MCP server that gives your terminal sessions a persistent memory:

gemini mcp add --transport http tempreon https://api.tempreon.com/functions/v1/tempreon-mcp/mcp -s user

Then /mcp auth tempreon and approve in the browser. The account-holder walkthrough, including the Gemini Code Assist notes, is in the Gemini CLI setup doc.