◉CLAUDE LABJP
●CC 2.1.327 — Claude Code 2.1.327 (11/18) adds claude mcp add-json, which reads a server's JSON from stdin●MCP.JSON — The same release stops project-scope mcp add and remove from wiping other keys in .mcp.json●SONNET 4.5 — Retires on the Claude API on 11/30, 11 days left. Sweep model IDs in code and saved settings in one pass●GATEWAY — Users report that behind a gateway, 1M-context models compact so late that each reply takes tens of seconds●NEON — Gemini 4 Neon went GA on 11/18. If you run it next to Claude Code, keep each tool's MCP config separate●NEW — Linked Billing 402 or 403? Find Whose Wallet Is Empty First●CC 2.1.327 — Claude Code 2.1.327 (11/18) adds claude mcp add-json, which reads a server's JSON from stdin●MCP.JSON — The same release stops project-scope mcp add and remove from wiping other keys in .mcp.json●SONNET 4.5 — Retires on the Claude API on 11/30, 11 days left. Sweep model IDs in code and saved settings in one pass●GATEWAY — Users report that behind a gateway, 1M-context models compact so late that each reply takes tens of seconds●NEON — Gemini 4 Neon went GA on 11/18. If you run it next to Claude Code, keep each tool's MCP config separate●NEW — Linked Billing 402 or 403? Find Whose Wallet Is Empty First
Articles/Claude Code
⟐ Claude Code/2026-11-19Intermediate

Using One MCP Server from Both Claude Code and Gemini CLI? Generate Both Configs from a Single Source

Paste a Claude Code .mcp.json entry into Gemini CLI and the HTTP server may refuse to connect. A side-by-side table of the differences (url vs httpUrl, variable expansion, server names) plus a Python script that writes both configs from one source file.

Claude Code289Gemini CLIMCP62ConfigurationComparison3

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.

ItemClaude CodeGemini CLI
Project config file.mcp.json (repository root).gemini/settings.json
How the transport is chosentype (stdio / http / sse / ws)Key name (command / httpUrl / url)
Streamable HTTP"type": "http" plus urlhttpUrl (url means SSE)
Where variables expandcommand, args, env, url, headersThe env block
Accepted variable forms${VAR} and ${VAR:-default}$VAR and ${VAR} (plus %VAR% on Windows)
When a variable is unsetKeeps the literal ${VAR} text; claude mcp list warnsBecomes an empty string
Server name caveatAvoid reserved namesAvoid _ (it confuses the policy parser)
First loadProject servers wait until you approve them interactivelystdio 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 list

In 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.

Share

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

⟐ Claude Code2026-09-04
The ~/.claude.json Rollback Is Fixed in v2.1.259. Putting Back What It Erased Is Still Your Job
Concurrent sessions used to silently roll back each other's ~/.claude.json changes. v2.1.259 fixed that, but nothing restores the trust settings and MCP servers you already lost. Here is how I find and rebuild them, with a small key-path diff script.
⟐ Claude Code2026-10-23
When a Nightly claude -p Said MCP Needed Authentication, I Added a Preflight That Splits Sleep From Keychain
Claude Code 2.1.307 fixed MCP failures caused by macOS sleep and a locked login keychain. Here is a preflight script that helps with or without the fix, and a way to match failures against sleep history.
⟐ Claude Code2026-10-23
When a Nightly claude -p Says MCP "Needs Authentication": Check Mac Sleep and the Keychain First
If an unattended claude -p run leaves "needs authentication" or MCP timeouts in the morning log, check whether the Mac slept or the login keychain was locked. What v2.1.307 changed, and what it still leaves to you.