Add a Remote MCP Server to Gemini CLI: httpUrl, Auth and Fixes

How to add a remote MCP server to Gemini CLI with gemini mcp add or settings.json, why httpUrl and url are different transports, how sign-in works, and what to do when /mcp says DISCONNECTED.

MCP Hunter team 14 October 2026 6 min read

A remote MCP server goes into Gemini CLI with one command [1]:

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

That writes an entry to .gemini/settings.json in the current project. Start gemini and type /mcp to see whether it connected and which tools it brought [1].

Everything below is checked against Gemini CLI's documentation on 14 October 2026, the day after release v0.64.0 [1][2][3].

TL;DR:

Pass --transport http. The default transport is stdio, so without it your URL is treated as a command to run [1].
Add --scope user for every project. The default scope is the project you are standing in [1].
httpUrl is Streamable HTTP, url is SSE. Writing a modern server's address under url connects with the wrong transport [1].
Sign-in is automatic. A 401 opens your browser; /mcp auth my-server signs in again when the token expires [1].
The timeout is in milliseconds and defaults to 10 minutes [1].

Add the server

gemini mcp add takes a name and an address. For a remote server, three flags matter [1]:

Flag	Default	What it does
`-t, --transport`	`stdio`	`http` for Streamable HTTP, `sse` for the older transport
`-s, --scope`	`project`	`user` writes to `~/.gemini/settings.json` instead
`-H, --header`	none	One HTTP header per flag, repeatable

So a server you want in every project, with a key, is:

gemini mcp add --scope user --transport http \
  --header "Authorization: Bearer $MY_SERVER_TOKEN" \
  my-server https://mcp.example.com/mcp

Name the server with hyphens, not underscores. Gemini CLI names each tool mcp_{serverName}_{toolName}, and its permission rules split that name at the first underscore after mcp_, so my_server breaks them where my-server does not [1].

gemini mcp list prints every server with its status, gemini mcp remove my-server deletes one, and gemini mcp disable and enable switch one off and on without deleting it [1].

Or write settings.json by hand

The command writes an mcpServers entry you can also write yourself, in ~/.gemini/settings.json for your user or .gemini/settings.json for one project. Project settings override user settings [2].

{
  "mcpServers": {
    "my-server": {
      "httpUrl": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer $MY_SERVER_TOKEN"
      },
      "timeout": 30000
    }
  }
}

The key that holds the address chooses the transport [1]:

Key	Transport
`httpUrl`	Streamable HTTP, what current servers speak
`url`	SSE, the transport Streamable HTTP replaced
`command`	A local process (stdio)

If an entry has more than one, httpUrl wins, then url, then command [2]. Cursor and VS Code both put a Streamable HTTP address under "url", so an entry copied from their docs or a README written for them lands on the SSE key here. If a server you know works shows DISCONNECTED, check this first. Is SSE deprecated in MCP? explains the two transports.

$MY_SERVER_TOKEN is read from your environment when the settings load, so the token stays out of a file you might commit. ${VAR} and ${VAR:-default} work too [2].

Other keys worth knowing

timeout: per request, in milliseconds, default 600,000 (10 minutes) [1]. 30 means 30 milliseconds, not seconds.
includeTools / excludeTools: an allow list and a deny list of tool names; a tool in both is excluded [1]. A shorter tool list is easier for the model to choose from, which how many tools an MCP server should have puts in numbers.
trust: true skips the confirmation prompt on every tool call from this server [1]. Leave it off for a server you have not vetted.

Gemini CLI does the MCP sign-in on its own. When a server answers 401, the CLI finds its authorization metadata, registers itself, opens your browser, and stores the token in ~/.gemini/mcp-oauth-tokens.json [1]. No configuration is needed:

{
  "mcpServers": {
    "my-server": { "httpUrl": "https://mcp.example.com/mcp" }
  }
}

Inside the CLI, /mcp auth lists the servers that need sign-in and /mcp auth my-server runs it again when a token expires [3].

The registration step is Dynamic Client Registration, which most servers accept. We read the authorization metadata of 169 servers that ask for credentials, from our registry census on 9 October 2026: 162 offered it [4]. For one that does not, register an app with the provider and put its ID in an oauth block with "clientId" [1].

Sign-in needs a browser on the same machine. The callback lands on http://localhost:<random-port>/oauth/callback, so it fails over SSH without forwarding and inside containers [1]. Set a fixed redirectUri in the oauth block if the provider wants one registered in advance [1].

When /mcp says DISCONNECTED

Startup errors are silent by default. The only sign is a line saying "MCP issues detected. Run /mcp list for status." [1] /mcp list inside the CLI, or gemini mcp list from the shell, shows the reason [1].

What you see	Usual cause	Fix
The server never appears	Added without `--transport http`, so it was saved as a command	Remove it and add it again with `--transport http`
It appears in one project only	Default scope is `project`	Add it again with `--scope user`
`DISCONNECTED` on a server that works elsewhere	The address is under `url`, so the CLI speaks SSE	Move it to `httpUrl`
Times out at once	`timeout` written in seconds	It is milliseconds: `30000` for 30 seconds
`401` with a header configured	The environment variable is unset where `gemini` starts	Export it in that shell
`DISCONNECTED` on a server that answers	It returned no usable tools, so the CLI closed it [1]	Check what `tools/list` returns
Sign-in never completes	No local browser, or a remote session	Sign in on a machine with a browser, or use a header token

For more detail, run gemini --debug and press F12 for the debug console [1]. MCP server errors covers what a 406, a CORS failure or a -32601 means on the server's side.

Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. If it works there and not in Gemini CLI, the problem is in your settings, not the server.

The same setup in other clients is in Claude Code, Codex, Cursor, VS Code, Cline, GitHub Copilot CLI, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.