The most tedious part of moving to a new work machine was carrying over my MCP servers.
Open the old config file, copy each server definition across, mistype an environment variable name, drop a closing brace, and only discover it when the tool list comes up empty. As an indie developer moving between app work and web work, that chore came back every time I changed hardware.
Antigravity CLI 1.1.16, released on August 20, turns that chore into a command. A new mcp subcommand gives you add, remove, list, enable, and disable for the user-level mcp_config.json. According to the official changelog, three flags — --type, --env, and --header — cover both stdio and HTTP servers.
I first read this as a change that removes places where my hand can slip. After living with it for a while, I also found the line between what the command can take care of and what you only learn by reading the file itself. Here is how it went when I rebuilt my setup.
The short version
agy mcpwrites only to the global~/.gemini/config/mcp_config.json. A per-workspace<workspace>/.agents/mcp_config.jsonis still managed separately.- Even after adding servers by command, read the resulting JSON at least once. Further down there is a ~100-line script that lists what is registered while masking secrets.
- A token you pass with
--headeris stored in the file in its expanded form, even if you wrote it as a shell variable. I had this one wrong myself.
Everything here was checked against the official docs (the MCP page and the changelog on antigravity.google) as of November 2026. The latest CLI is v1.5.11 from November 18, and as far as the changelog shows, nothing since 1.1.16 has changed how the mcp subcommand is used.
Where the config lives, and what the command touches
The official docs list two files the CLI reads MCP definitions from, plus the ones plugins bring along.
| Kind | Location | Scope | Managed by agy mcp? |
|---|---|---|---|
| Global | ~/.gemini/config/mcp_config.json | Every project | Yes |
| Workspace | <workspace>/.agents/mcp_config.json | That workspace only | No (edit by hand) |
| Plugin | <plugin-root>/mcp_config.json | While the plugin is enabled | No (the plugin owns it) |
There is also more than one way in. Besides the subcommand, typing /mcp inside the CLI opens the MCP manager, and you can always open the file yourself. This is how I choose:
| Entry point | Good for | Not good for |
|---|---|---|
agy mcp add / remove | Moving to new hardware, reproducing a setup from a script | Workspace config, fine-grained keys like timeoutSeconds |
agy mcp enable / disable | Temporarily taking a heavy or suspicious server out | Turning off individual tools |
/mcp panel | Toggling while watching connection status and logs | Leaving a record you can replay |
| Hand-editing the file | Keys with no flag: enabledTools, tools.eager, oauth | Typos and missing braces |
In one sentence: keep whatever should be identical on every machine in commands, and keep project-specific setup and flagless details in files.
What I was redoing by hand every time
When I list the ways the migration used to break, the failures fall into clear categories.
| Failure | When you notice | Via the subcommand |
|---|---|---|
| Missing closing brace | After launch, nothing in that file loads | You never write JSON at all |
args written as a string, not an array | After launch, that one server fails | Built from the argument list |
| Misspelled server name | When a tool call fails | list confirms it right away |
| Typo in an environment variable key | Surfaces as an auth error | --env keeps the shape consistent |
| Misspelled key for a remote URL | The handshake never comes back | --type decides the key |
My older list also had "trailing comma" on it, but CLI 1.1.24 (September 2) changed that: mcp_config.json now tolerates // and /* */ comments and trailing commas. And since 1.1.14 (August 18), a single malformed entry is logged and skipped while the remaining servers still load.
A file whose overall structure is broken — a missing brace, say — still fails on every version, because the parser can't tell where one entry ends. Catching that before launch is the subject of Find the one broken MCP entry before Antigravity starts, with a Node script under 60 lines. This piece sits one step earlier: not writing the JSON by hand in the first place.
Adding a stdio server in one line
The form I use most is a stdio server, launched as a local process.
# Register with a name, a type, and the launch command
agy mcp add filesystem \
--type stdio \
-- npx -y @modelcontextprotocol/server-filesystem "$HOME/projects"One honest caveat. The official changelog names the subcommands and the three flags, but I could not confirm in the official docs the exact argument order — passing the launch command after --, or putting the URL last. Please run agy mcp add --help on your version once and follow what it shows. Whatever the syntax, the script in the next section will tell you whether args landed as an array.
For servers that need environment variables, add --env:
agy mcp add github \
--type stdio \
--env "GITHUB_TOKEN=${GITHUB_TOKEN}" \
-- npx -y @modelcontextprotocol/server-githubThen confirm right away:
agy mcp listIf the name and type show up as expected, the registration went through. I trained my hands to treat list as part of add. Reading back what you just wrote is an obvious habit — the real gain is doing it without opening the file.
HTTP servers differ only in how you pass headers
For a remote MCP server, use --type http and pass authentication with --header:
agy mcp add my-remote-tools \
--type http \
--header "Authorization: Bearer ${MY_MCP_TOKEN}" \
https://mcp.example.com/mcpPer the official docs, remote servers must speak Streamable HTTP, and in the file the endpoint goes under serverUrl (url also works). Always include the scheme. A config that starts at the host, like mcp.example.com/mcp, doesn't fail until the handshake.
And this is the point I most want to pass on. Your shell expands ${MY_MCP_TOKEN} before the command ever sees it, so the file ends up holding the actual token. Going by the property list in the docs, mcp_config.json has no way to reference an environment variable. Using a variable keeps the token out of your shell history; it does nothing for the file.
Reading the file right after you write it
Whatever the entry point, what gets loaded is the file. So I keep one script that lists what is registered. The problem it solves: when a server shows up in list but doesn't work, you can check argument shape, URL shape, disabled state, and secret exposure in one pass.
#!/usr/bin/env python3
"""mcp_inspect.py — mcp_config.json を読み、登録内容を秘密を伏せて一覧にする。
使い方: python3 mcp_inspect.py [設定ファイル ...](省略時はグローバルと ./.agents の2つ)"""
import json, os, stat, sys
from urllib.parse import urlparse
def strip_jsonc(text):
"""文字列の中身は残したまま、// と /* */ のコメントと末尾カンマを取り除く。"""
out, i, n, in_str = [], 0, len(text), False
while i < n:
c = text[i]
if in_str:
out.append(c)
if c == "\\" and i + 1 < n:
out.append(text[i + 1]); i += 2; continue
if c == '"':
in_str = False
i += 1; continue
if c == '"':
in_str = True; out.append(c); i += 1; continue
if text.startswith("//", i):
j = text.find("\n", i); i = n if j < 0 else j; continue
if text.startswith("/*", i):
j = text.find("*/", i + 2); i = n if j < 0 else j + 2; continue
out.append(c); i += 1
s, res, in_str, i = "".join(out), [], False, 0
while i < len(s): # 2巡目: 文字列の外にある「, の直後が } か ]」だけを落とす
c = s[i]
if in_str:
res.append(c)
if c == "\\" and i + 1 < len(s):
res.append(s[i + 1]); i += 2; continue
if c == '"':
in_str = False
elif c == '"':
in_str = True; res.append(c)
elif c == "," and s[i + 1:].lstrip()[:1] in ("}", "]"):
pass
else:
res.append(c)
i += 1
return "".join(res)
def mask(v):
v = str(v)
return v if len(v) <= 8 or "${" in v or "YOUR_" in v else v[:4] + "…(" + str(len(v)) + "文字)"
def inspect(path):
problems = 0
print(f"== {path}")
if not os.path.exists(path):
print(" (ファイルなし)"); return 0
mode = stat.S_IMODE(os.stat(path).st_mode)
if mode & 0o077:
print(f" ⚠ 権限 {oct(mode)}: 自分以外も読めます(chmod 600 を推奨)")
raw = open(path, encoding="utf-8-sig").read()
try:
data = json.loads(strip_jsonc(raw))
except json.JSONDecodeError as e:
print(f" ❌ JSON として読めません: {e.msg}({e.lineno} 行 {e.colno} 列付近)"); return 1
servers = data.get("mcpServers")
if not isinstance(servers, dict):
print(" ❌ ルートに mcpServers がありません"); return 1
for name, s in servers.items():
flag = "停止中" if s.get("disabled") else "有効"
url = s.get("serverUrl") or s.get("url")
if "command" in s and url:
print(f" ❌ {name}: command と serverUrl の両方があります(どちらか一つ)"); problems += 1
if "command" in s:
args = s.get("args", [])
if not isinstance(args, list):
print(f" ❌ {name}: args が配列ではありません → {args!r}"); problems += 1; args = [args]
print(f" [{flag}] {name} stdio {s['command']} {' '.join(map(str, args))}")
for k, v in (s.get("env") or {}).items():
print(f" env {k}={mask(v)}")
elif url:
p = urlparse(url)
if p.scheme not in ("http", "https") or not p.netloc:
print(f" ❌ {name}: URL にスキームかホストがありません → {url}"); problems += 1
print(f" [{flag}] {name} http {url}")
for k, v in (s.get("headers") or {}).items():
print(f" header {k}: {mask(v)}")
else:
print(f" ❌ {name}: command も serverUrl もありません"); problems += 1
return problems
paths = sys.argv[1:] or [os.path.expanduser("~/.gemini/config/mcp_config.json"), ".agents/mcp_config.json"]
total = sum(inspect(p) for p in paths)
print(f"問題 {total} 件"); sys.exit(1 if total else 0)Three notes on why it is written this way:
- Since 1.1.24 allows comments and trailing commas, the script removes them before handing the text to the standard
jsonmodule — without touching anything inside strings, so the//in a URL survives. - Token and env values are shown as the first four characters plus a length. You can paste the output into a screen share or a log without leaking anything.
- It exits with status 1 if it finds any problem, so placed at the end of a migration script it stops you from carrying on with a broken setup.
Here is the output on Ubuntu with Python 3.10.12, fed a deliberately broken sample (the messages are in Japanese because that is how I wrote them; the meaning is in the table below):
== sample.json
⚠ 権限 0o644: 自分以外も読めます(chmod 600 を推奨)
[有効] filesystem stdio npx -y @modelcontextprotocol/server-filesystem /Users/me/projects
❌ github: args が配列ではありません → '-y @modelcontextprotocol/server-github'
[有効] github stdio npx -y @modelcontextprotocol/server-github
env GITHUB_TOKEN=ghp_…(24文字)
[停止中] heavy-indexer stdio node /opt/indexer.js
[有効] my-remote-tools http https://mcp.example.com/mcp
header Authorization: Bear…(31文字)
❌ typo-remote: URL にスキームかホストがありません → mcp.example.com/mcp
[有効] typo-remote http mcp.example.com/mcp
問題 2 件The first line warns that the file is readable by others (suggesting chmod 600); [有効] means enabled and [停止中] means disabled; the two ❌ lines flag args that isn't an array and a URL with no scheme. With a missing brace, the script reports that the file can't be parsed, with the line and column, and again exits 1.
Isolate with disable, not remove
The quiet win in the subcommand for me was disable.
When an MCP server misbehaved, I used to cut its block out of the config, park it somewhere, and paste it back when I was done. If I forgot where I parked it, it was gone.
agy mcp disable heavy-indexer # keep the definition, stop loading it
agy mcp list # check the state
agy mcp enable heavy-indexer # bring it backThe docs list a disabled property (default false) that, when true, suspends the connection while keeping the configuration. That is what the script reads to print the disabled marker. Use agy mcp remove <name> only for servers you no longer need.
When startup feels slow, the server I suspect first is not the one I added most recently but the one carrying the heaviest work. I could change the order of suspicion only because taking a server out and putting it back became cheap.
The same 1.1.16 release also fixed the /mcp panel dropping enabledTools, timeoutSeconds, url, and tools.eager when you toggled a server. If you toggled servers from the panel on an earlier version, it is worth checking that the keys you added by hand are still there.
When it doesn't work: a triage table
When a server I added by command doesn't behave, I check in this order.
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| Listed, but no tools appear | Registered but still disabled | Script shows it as disabled | agy mcp enable <name> |
| A server you added for a project is missing | You meant global but the project uses its workspace file, or the reverse | Pass both files to the script and compare | Shared setup goes global; project-specific goes in .agents/mcp_config.json |
| A stdio server dies right after launch | args became a single string | Script's "args is not an array" error | Remove and re-add using the order from --help |
| Remote handshake never returns | No scheme in the URL, or the server isn't Streamable HTTP | Script's URL check, and the server's transport | Re-add with the scheme (https) written out |
| Auth errors keep coming | Stale token, or a variable that expanded to empty | Does the masked length match what you expect? (empty means short) | Set the variable, then re-add |
| Every server vanished | The file's overall structure is broken | "Cannot parse" error with line and column | Fix the brace at that position |
Scripting the setup so it travels
Once these operations were commands, the setup itself could live in a shell script. I keep mine as one file and run the checker at the end.
#!/usr/bin/env bash
# mcp-bootstrap.sh — recreate the MCP setup on a new machine
set -euo pipefail
: "${GITHUB_TOKEN:?Please set GITHUB_TOKEN}"
# Don't stop if an entry with the same name already exists
safe_add() {
local name="$1"; shift
agy mcp remove "$name" >/dev/null 2>&1 || true
agy mcp add "$name" "$@"
}
safe_add filesystem --type stdio \
-- npx -y @modelcontextprotocol/server-filesystem "$HOME/projects"
safe_add github --type stdio \
--env "GITHUB_TOKEN=${GITHUB_TOKEN}" \
-- npx -y @modelcontextprotocol/server-github
chmod 600 "$HOME/.gemini/config/mcp_config.json"
python3 "$(dirname "$0")/mcp_inspect.py" "$HOME/.gemini/config/mcp_config.json"safe_add is there so running the script twice gives the same result. Migrations get interrupted and restarted; that happens.
Secrets come from the environment at run time, never from the script. The : check at the top stops the run before it can leave a half-built configuration behind. I took the same approach — credentials through environment variables rather than an interactive sign-in — in Running Antigravity CLI 1.1.13 on a machine you cannot sign in from.
Common misunderstandings
"If I manage servers by command, I can stop thinking about the config file." Only the entry point changed; the destination is the same file. It still belongs in your backups, and keys with no flag — enabledTools, oauth — are still written by hand.
"disable and remove are the same; either way the server stops loading." disable sets disabled: true and keeps the definition. remove deletes it. Use remove mid-investigation and you'll be reconstructing arguments from memory when you want it back.
"Passing the token as a variable keeps it out of the file." As above, the expanded value is what gets saved. What you can actually protect is the file's permissions and where it lives.
Where I tripped, and the line I keep now
When I first wrote these notes, I believed that --header "Authorization: Bearer ${MY_MCP_TOKEN}" meant the real token would never land anywhere. I was treating "not in my history" and "not in the file" as the same thing.
I noticed only after I started running the checker after every migration. The masked header length was plainly the length of a token, not a variable name. Once I stopped writing JSON by hand, I had started imagining the file's contents instead of reading them.
These days the rule is commands for the way in, the real file for the check. The global config is chmod 600 and stays out of synced folders and repositories. A workspace .agents/mcp_config.json tends to end up committed, so I don't give it anything that carries a token.
The next place you'll get stuck
Once adding servers by command feels natural, the next snag is usually the workspace side. There are reports of the CLI logging that it found a project-level file while the servers in it never start; I wrote up how to verify startup from the outside in The project-local mcp_config.json is read, but no MCP server starts — checking with a one-file probe.
The other is name collisions with plugins. Since CLI 1.2.2, MCP servers bundled with a plugin are automatically renamed to <plugin>_<server>, so they no longer clash with servers you registered yourself. If an unfamiliar prefix shows up in list or in tool names, it came from a plugin. What I look at before installing one is in Three things to check on a Marketplace partner plugin's page before you install it.
What to do next
Run agy mcp list once, then point the checker above at your global config. If you see a permissions warning, or a server whose name you can't place, that is the first thing to tidy.
I'm still refining how I carry my setup around, but just not having to copy JSON by hand has made rebuilding an environment feel much lighter. That one extra check is the step I keep even on days when I'm in a hurry.