It was a late evening, and I was trying to make a small MCP server, one that pulls store reviews for my wallpaper app, callable from both Claude Code and Gemini CLI. Claude Code listed its tools right away. I pasted the same definition into Gemini CLI's settings, and that one server sat at DISCONNECTED.
The two stdio servers were fine in both CLIs. Only the one listening over HTTP was stuck. I suspected the token, then the server logs, and spent about half an hour going the long way round before realizing the cause was a single word in the config.
Here is the short version up front: both CLIs use a key called mcpServers, but what goes inside it is not written the same way. Because the two files look alike, it is easy to assume a copy-paste will do. As an indie developer who uses both tools side by side, I want to write down the line I drew after that evening.
Why only the HTTP server failed in Gemini CLI
In Claude Code's .mcp.json, a remote server looks like this:
{
"mcpServers": {
"store-reviews": {
"type": "http",
"url": "https://mcp.example.com/mcp"
}
}
}Move that block into mcpServers in .gemini/settings.json and Gemini CLI simply ignores type. Gemini CLI decides the transport from the key name: httpUrl means Streamable HTTP, url means SSE, and command means stdio.
So the moment I wrote url, I was speaking SSE to a Streamable HTTP server. The server was up and the token was correct. The only thing wrong was the name of one key.
The trap works in the other direction too. Claude Code reads an entry with no type as a stdio server, so a Gemini-style {"httpUrl": ...} pasted into .mcp.json will not connect. If an entry has a url but no type, Claude Code skips it with a message asking you to add "type": "http".
The differences, in one table
I read both sets of docs side by side and kept only the rows likely to bite. This is based on the Claude Code documentation (the MCP chapter) and docs/tools/mcp-server.md in the Gemini CLI repository, as of November 19, 2026.
| Item | Claude Code | Gemini CLI |
|---|---|---|
| Project config file | .mcp.json (repository root) | .gemini/settings.json |
| How the transport is chosen | type (stdio / http / sse / ws) | Key name (command / httpUrl / url) |
| Streamable HTTP | "type": "http" plus url | httpUrl (url means SSE) |
| Where variables expand | command, args, env, url, headers | The env block |
| Accepted variable forms | ${VAR} and ${VAR:-default} | $VAR and ${VAR} (plus %VAR% on Windows) |
| When a variable is unset | Keeps the literal ${VAR} text; claude mcp list warns | Becomes an empty string |
| Server name caveat | Avoid reserved names | Avoid _ (it confuses the policy parser) |
| First load | Project servers wait until you approve them interactively | stdio servers don't connect in an untrusted folder |
The two rows I watch most closely are the variable ones. A value with a default like ${TOKEN:-dev} works in Claude Code, but it is not a form the Gemini CLI docs describe. An unset variable also travels differently: Claude Code passes the literal string ${VAR}, while Gemini CLI passes an empty string.
Both failures share the same shape: the server starts quietly with the wrong value. By the time it shows up as an authentication error, the config file is the last place you think to look.
One more difference. Gemini CLI hides inherited host variables whose names match patterns like *TOKEN* or *KEY* before it starts a server. Anything the server needs has to be listed explicitly in env.
One source file, written out in two dialects
At first I kept the two files in sync by hand. It did not go well. I added a server to one and forgot the other, and after the third time I stopped trying.
Define once; translate on the way out. That is the rule I work by now. A neutral mcp-servers.src.json, shaped for neither tool, is the source of truth, and a small script generates both files from it.
The source looks like this. The one convention is that env values hold only the variable's name, not any expansion syntax.
{
"files": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./assets"]
},
"issue-tracker": {
"transport": "stdio",
"command": "node",
"args": ["tools/issue-mcp.js"],
"env": { "TRACKER_TOKEN": "TRACKER_TOKEN" }
},
"store-reviews": {
"transport": "http",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer ${REVIEWS_TOKEN}" }
}
}Here is the script. It keeps every other key already in the target files ($schema in .mcp.json, other Gemini settings) and replaces only mcpServers.
#!/usr/bin/env python3
"""Generate .mcp.json and .gemini/settings.json from mcp-servers.src.json."""
import json
import os
import re
import sys
from pathlib import Path
SRC = Path("mcp-servers.src.json")
CLAUDE = Path(".mcp.json")
GEMINI = Path(".gemini/settings.json")
VAR_NAME = re.compile(r"^[A-Z_][A-Z0-9_]*$")
def load_json(path, default):
if not path.exists():
return default
try:
return json.loads(path.read_text(encoding="utf-8"))
except json.JSONDecodeError as e:
# Re-serializing a commented settings.json would drop the comments, so stop instead
sys.exit(f"{path}: not valid JSON ({e}). Remove comments, then run again")
def env_block(name, spec):
out = {}
for key, var in spec.get("env", {}).items():
if not VAR_NAME.match(var):
sys.exit(f"{name}.env.{key}: write only the variable name here ({var!r})")
out[key] = "${" + var + "}" # the one form both CLIs read; no :-default on purpose
return out
def to_claude(name, spec):
if spec["transport"] == "stdio":
entry = {"type": "stdio", "command": spec["command"], "args": spec.get("args", [])}
env = env_block(name, spec)
if env:
entry["env"] = env
return entry
# Without "type", Claude Code reads the entry as stdio, so always write it
entry = {"type": spec["transport"], "url": spec["url"]}
if spec.get("headers"):
entry["headers"] = spec["headers"]
return entry
def to_gemini(name, spec):
if "_" in name:
sys.exit(f"{name}: avoid '_' in server names for Gemini CLI")
t = spec["transport"]
if t == "stdio":
entry = {"command": spec["command"], "args": spec.get("args", [])}
env = env_block(name, spec) # names like *TOKEN* only reach the server if listed here
if env:
entry["env"] = env
return entry
entry = {"httpUrl": spec["url"]} if t == "http" else {"url": spec["url"]} # "url" means SSE
headers = spec.get("headers", {})
if any("${" in v for v in headers.values()):
print(f"skip: {name} has a variable in its headers; not writing it for Gemini", file=sys.stderr)
return None
if headers:
entry["headers"] = headers
return entry
def main():
servers = load_json(SRC, None)
if not servers:
sys.exit(f"{SRC} is missing or empty")
for name, spec in servers.items():
for var in spec.get("env", {}).values():
if var not in os.environ:
print(f"warning: {var} used by {name} is not set in this shell", file=sys.stderr)
claude = load_json(CLAUDE, {})
gemini = load_json(GEMINI, {})
claude["mcpServers"] = {n: to_claude(n, s) for n, s in servers.items()}
g = {n: e for n, e in ((n, to_gemini(n, s)) for n, s in servers.items()) if e is not None}
gemini["mcpServers"] = g
CLAUDE.write_text(json.dumps(claude, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
GEMINI.parent.mkdir(exist_ok=True)
GEMINI.write_text(json.dumps(gemini, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"claude={len(claude['mcpServers'])} gemini={len(g)}")
if __name__ == "__main__":
main()Run against the source above, it prints claude=3 gemini=2, and store-reviews drops out of the Gemini side with a skip: line. The script exists to prevent three specific accidents.
The first is a transport mix-up. to_gemini always turns http into httpUrl, and to_claude always writes type. The second is variable dialects: the source holds names only, and the output uses ${VAR}, the one form both CLIs read. I deliberately avoid the default-value syntax.
The third is where secrets live. The Gemini CLI docs describe expansion in the env block, so a server with a variable in its headers is not written for Gemini at all; the script just warns. I registered that one server by hand, once, in ~/.gemini/settings.json, which never goes into the repository.
Stopping instead of overwriting when settings.json will not parse is also intentional. Some Gemini CLI config examples include comments, and reading the file with the json module and writing it back would silently drop them.
Check both CLIs after every write
After generating, I ask both CLIs for their server lists and compare.
python3 tools/sync_mcp.py
claude mcp list
gemini mcp listIn Claude Code, servers read from .mcp.json may show ⏸ Pending approval. Nothing is broken; Claude Code simply won't use them until you start claude interactively and approve them.
In Gemini CLI, stdio servers in an untrusted folder show as Disconnected. Run gemini trust for the current folder, then list again.
It is also worth checking your Claude Code version. Version 2.1.327, released on November 17, fixed a bug where project-scope claude mcp add and claude mcp remove deleted other top-level keys in .mcp.json, such as $schema or another tool's servers. From the same release, claude mcp add --scope project stops instead of overwriting when .mcp.json lists servers at the top level with no mcpServers key.
If you run several tools against the same repository, an older version could take another tool's settings down with it. A quick claude --version to confirm 2.1.327 or later is enough.
Deciding which side to fix
When two CLIs share a set of servers and something breaks, the natural question is which config to fix. My answer is neither: I fix the source and regenerate. Editing one output directly only lasts until the next run, and then I meet the same bug again.
The single exception is the secret-bearing server in Gemini's user settings. The skip: line printed on every run reminds me that it lives outside the source.
If a variable is reaching your server as literal text, I covered the triage in Only the Plugin's MCP Server Fails to Authenticate. And if you want to go further, into servers that connect fine but quietly lose tools, the member article The MCP Server Connects Fine and Still Hands Back Zero Tools is a good next step.
For today, I'd suggest opening your .gemini/settings.json and checking, one entry at a time, whether every server written with url really speaks SSE. In my case, that one word was the whole fix.