◉ANTIGRAVITY LABJP
Articles/Integrations
⬡ Integrations/2026-08-22Beginner

Adding MCP Servers Without Opening the Config File: The agy mcp Subcommand

How to register and pause MCP servers with the mcp subcommand added in Antigravity CLI 1.1.16 — plus the global vs. workspace config split, why a token passed as a shell variable still lands in the file, a script that lists what is registered with secrets masked, and a symptom-based triage table (checked against the official docs as of November 2026).

MCP29Antigravity CLI45Setup6Configuration5

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 mcp writes only to the global ~/.gemini/config/mcp_config.json. A per-workspace <workspace>/.agents/mcp_config.json is 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 --header is 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.

KindLocationScopeManaged by agy mcp?
Global~/.gemini/config/mcp_config.jsonEvery projectYes
Workspace<workspace>/.agents/mcp_config.jsonThat workspace onlyNo (edit by hand)
Plugin<plugin-root>/mcp_config.jsonWhile the plugin is enabledNo (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 pointGood forNot good for
agy mcp add / removeMoving to new hardware, reproducing a setup from a scriptWorkspace config, fine-grained keys like timeoutSeconds
agy mcp enable / disableTemporarily taking a heavy or suspicious server outTurning off individual tools
/mcp panelToggling while watching connection status and logsLeaving a record you can replay
Hand-editing the fileKeys with no flag: enabledTools, tools.eager, oauthTypos 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.

FailureWhen you noticeVia the subcommand
Missing closing braceAfter launch, nothing in that file loadsYou never write JSON at all
args written as a string, not an arrayAfter launch, that one server failsBuilt from the argument list
Misspelled server nameWhen a tool call failslist confirms it right away
Typo in an environment variable keySurfaces as an auth error--env keeps the shape consistent
Misspelled key for a remote URLThe 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-github

Then confirm right away:

agy mcp list

If 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/mcp

Per 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 json module — 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 back

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

SymptomLikely causeHow to checkFix
Listed, but no tools appearRegistered but still disabledScript shows it as disabledagy mcp enable <name>
A server you added for a project is missingYou meant global but the project uses its workspace file, or the reversePass both files to the script and compareShared setup goes global; project-specific goes in .agents/mcp_config.json
A stdio server dies right after launchargs became a single stringScript's "args is not an array" errorRemove and re-add using the order from --help
Remote handshake never returnsNo scheme in the URL, or the server isn't Streamable HTTPScript's URL check, and the server's transportRe-add with the scheme (https) written out
Auth errors keep comingStale token, or a variable that expanded to emptyDoes the masked length match what you expect? (empty means short)Set the variable, then re-add
Every server vanishedThe file's overall structure is broken"Cannot parse" error with line and columnFix 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.

Share

Thank You for Reading

Antigravity 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

⬡ Integrations2026-10-19
Connecting GitHub MCP to Antigravity CLI: The Fix Was One Word, url to serverUrl
To use GitHub MCP from Antigravity CLI, the url key in your config has to become serverUrl. Based on the official MCP docs, here are the remote and Docker setups, a small script that checks the file before you load it, where to keep the token, and the order to debug in.
⬡ Integrations2026-10-22
The Project-Local mcp_config.json Is Read, but No MCP Server Starts — Checking With a One-File Probe
Antigravity CLI logs that it is using a project-local config, yet the MCP servers in it never start. Where the official issue stands (still open as of November 2026), what that log line does and does not promise, a tiny probe server to check your own setup, a table for telling similar symptoms apart, and realistic ways to keep MCP servers per project.
⬡ Integrations2026-10-10
Figma MCP or Stitch MCP: Choosing by Whether the Screen Already Exists
When you turn a screen into code, which MCP should Antigravity talk to: Figma or Stitch? One question settles it: does the correct screen already exist? Here is the rule I use, a switching routine, and a small script for the days I can't decide.