All MCP setup guides
MCPGemini CLI

How to Add a Remote MCP Server to Gemini CLI

Use url with "type": "http" — httpUrl still works but is deprecated, and the Gemini CLI docs page still describes the older url-means-SSE behaviour. Plus the scope flag people forget and who Gemini CLI still serves after the 2026 changes.

Last verified October 15, 2026

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, use url with "type": "http" — the older httpUrl field still works but is deprecated.

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:

  • A Gemini API key, including Gemini Enterprise Agent Platform keys
  • Existing Gemini Code Assist Standard or Enterprise licenses

As of October 2026, that second route is closing to newcomers: after October 9, 2026, Google no longer sells new Standard or Enterprise subscriptions. Annual renewals and additional licenses end January 31, 2027, and monthly renewals end December 31, 2027. Existing licenses keep working; if you're starting fresh, use a Gemini API key.

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 API-key and enterprise routes, 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": {
      "url": "https://mcp.example.com/mcp",
      "type": "http",
      "oauth": { "enabled": true }
    }
  }
}

url, type, and the older httpUrl

In current Gemini CLI, use url with "type": "http". That selects Streamable HTTP, the transport hosted MCP servers use, and it's exactly what gemini mcp add --transport http writes. "type": "sse" selects SSE.

Two older patterns still work:

  • httpUrl still gives Streamable HTTP, but Gemini CLI now marks it as deprecated and prints a warning asking you to migrate to url with type: "http". Existing configs keep working.
  • url with no type tries Streamable HTTP first and, if that connection fails for a reason other than a 401, falls back to SSE. A 401 goes to OAuth handling before any fallback.

This is worth stating plainly because Gemini CLI's own MCP docs page still describes the older behaviour, where url meant SSE and type isn't mentioned. The code moved on (it's been this way since roughly v0.22); the docs page hasn't caught up yet.

Gemini CLI is also deliberately quiet when a server doesn't connect: 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 first when something seems off.

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

Qwen Code, which is built on the Gemini CLI lineage, has not made this change: there, url still means SSE and httpUrl is still the Streamable HTTP field. Gemini CLI moved on; Qwen Code kept the older behaviour.

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, 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

  • A deprecation warning mentions httpUrl. The entry predates the current format. It still works; to silence the warning, change httpUrl to url and add "type": "http".
  • The logs say "attempting SSE fallback". The Streamable HTTP connection failed and Gemini CLI tried SSE instead, which happens with a url that has no type. Check the URL, including the path and any trailing slash, and add "type": "http" so the client stays on Streamable HTTP.
  • 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 url, 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 works from your legacy extension manifests: it converts extensions into Antigravity plugins, commands into skills, and any MCP server definitions it finds into mcp_config.json entries. It is not a substitute for the first-launch onboarding pass, which is what covers global configurations. 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.

Sources

The dated claims on this page were checked against these vendor documents. Client UIs move constantly, so if one of these has changed since the date shown, trust the vendor over this page — and tell us.

Frequently asked questions

Should a remote MCP server in Gemini CLI use url or httpUrl?
Use url with "type": "http", which is what gemini mcp add --transport http writes. That selects Streamable HTTP; "type": "sse" selects SSE. The older httpUrl field still works but is deprecated and prints a warning. A url with no type tries Streamable HTTP first and falls back to SSE if that fails. Gemini CLI's docs page still describes url as SSE, so the docs lag the code. Connection errors are quiet by default, so if something is off, run /mcp list first, then /mcp auth followed by the server name.
Where do I add an MCP server in Gemini CLI, and how do I make it global?
The fastest way is one command — gemini mcp add --transport http, then the name, the URL, and -s user, which writes the entry to your user-level ~/.gemini/settings.json so it is available in every project. Without -s, Gemini CLI defaults to project scope and the entry only applies to the directory you ran it in.
Gemini CLI stopped serving my requests. Is that a config problem?
No. On June 18, 2026, Gemini CLI stopped serving requests for consumer Google accounts — free, Google AI Pro, and Ultra. It continues to work with a Gemini API key and with existing Gemini Code Assist Standard or Enterprise licenses. Google stopped selling new Standard and Enterprise subscriptions after October 9, 2026, so new users should start with a Gemini API key. Google's own CLI README still advertises a free tier for personal accounts; that line predates the change.