作業機を入れ替えたとき、いちばん面倒だったのが MCP サーバーの移植でした。
旧環境の設定ファイルを開き、サーバーの定義をひとつずつ新環境へ書き写します。環境変数の名前を打ち間違え、閉じ括弧をひとつ落とし、起動してツール一覧が空になって初めて気づく——個人開発でアプリと Web を行き来していると、この作業が機材の入れ替えのたびに戻ってきます。
8月20日に出た Antigravity CLI 1.1.16 で、この移植作業がコマンドになりました。mcp サブコマンドが追加され、add / remove / list / enable / disable でユーザーレベルの mcp_config.json を扱えます。公式の変更履歴によれば、--type・--env・--header の三つで stdio と HTTP のどちらも登録できます。
私はこの変更を、機能追加というより「手が滑る余地を消す変更」として受け取りました。ただ、使い込むうちに、コマンドに任せてよい部分と、ファイルの実物を見ないと分からない部分の境目も見えてきました。以下、実際に構成を組み直した順に書き残します。
最初にお伝えしたいこと
結論を先に置きます。
agy mcpが書き込むのは グローバルの~/.gemini/config/mcp_config.jsonだけ です。ワークスペースごとの<workspace>/.agents/mcp_config.jsonは別に管理します- コマンドで足したあとも、登録された JSON の実物を一度は読む ことをおすすめします。後半に、秘密を伏せたまま中身を一覧にする 100 行ほどのスクリプトを載せました
--headerに渡したトークンは、シェルで変数展開しても 展開後の値がそのままファイルに保存 されます。ここは私自身が誤解していた点です
本文の版は、2026年11月時点の公式ドキュメント(antigravity.google の MCP ページと変更履歴)で確かめています。CLI は 11月18日の v1.5.11 が最新で、変更履歴を見るかぎり、mcp サブコマンドの使い方に関わる変更はその後ありません。
設定ファイルの置き場所と、コマンドが触る範囲
公式ドキュメントでは、CLI が MCP サーバーの定義を読むファイルは二つです。
| 種類 | 場所 | 効く範囲 | agy mcp で触れるか |
|---|---|---|---|
| グローバル | ~/.gemini/config/mcp_config.json | すべてのプロジェクト | 触れる |
| ワークスペース | <workspace>/.agents/mcp_config.json | そのワークスペースだけ | 触れない(手で編集) |
| プラグイン同梱 | <plugin-root>/mcp_config.json | プラグインを有効にしている間 | 触れない(プラグイン側で管理) |
入口も一つではありません。コマンドのほかに、CLI の中で /mcp と打って開く MCP マネージャーがあり、もちろん手でファイルを開くこともできます。どれを選ぶかは、次の基準で決めています。
| 入口 | 向いている場面 | 苦手なこと |
|---|---|---|
agy mcp add / remove | 新しい機材への移植、スクリプトでの再現 | ワークスペース側の設定、timeoutSeconds などの細かい項目 |
agy mcp enable / disable | 重い・怪しいサーバーを一時的に外す | どのツールだけ止めるか、といった粒度 |
/mcp パネル | 接続状態を見ながらの切り替え、ログの確認 | 手順の記録と再現 |
| ファイルの手編集 | enabledTools・tools.eager・oauth など、フラグにない項目 | 綴りや括弧の打ち間違い |
一文にまとめると、誰の作業機でも同じにしたい構成はコマンドで、プロジェクト固有の構成とフラグにない細かい項目はファイルで 持つのが、いまのところいちばん素直です。
手で書き写していたとき、毎回やり直していたこと
移植で失敗した箇所を並べると、性質がはっきり分かれます。
| 失敗の形 | 気づくタイミング | コマンド経由なら |
|---|---|---|
| 閉じ括弧の抜け | 起動後。そのファイルのサーバーがすべて読めない | そもそも JSON を書かない |
args を配列でなく文字列で書く | 起動後。該当サーバーだけ落ちる | 引数の並びから組み立てられる |
| サーバー名の綴り違い | ツールを呼んだとき | list で登録直後に確認できる |
| 環境変数キーの打ち間違い | 認証エラーとして表面化 | --env で渡す形が揃う |
| リモートの URL を書くキーの綴り違い | 握手が返らない | --type でキーが決まる |
以前の私の一覧には「末尾のカンマ」も入っていましたが、これは CLI 1.1.24(9月2日)で事情が変わりました。mcp_config.json に // や /* */ のコメント、末尾のカンマがあっても読めるようになっています。また 1.1.14(8月18日)からは、定義の壊れた1件はログに記録して読み飛ばし、残りのサーバーは読み込まれます。
それでも、閉じ括弧が足りないようにファイル全体の構造が崩れていれば、どの版でも読めません。どこまでが1件なのかをパーサーが決められないからです。この「起動前に落とす」側の話は、MCP サーバーが1本も起動しない原因は、起動前の 60 行足らずで特定できますで扱いました。今回はもう一段手前、そもそも手で書かずに済ませる側の話です。
stdio サーバーを1行で足す
いちばん使う形から見ていきます。ローカルのプロセスとして起動する stdio サーバーです。
# 名前・種別・起動コマンドを渡して登録する
agy mcp add filesystem \
--type stdio \
-- npx -y @modelcontextprotocol/server-filesystem "$HOME/projects"ここで一つお断りがあります。公式の変更履歴に書かれているのはサブコマンド名と --type・--env・--header の三つのフラグまでで、-- で区切って起動コマンドを渡す書き方や、URL を最後に置く並びは、公式ドキュメントでは確認できていません。お使いの版で agy mcp add --help を一度表示して、並びをそれに合わせてください。どの書き方であっても、登録後に次の節のスクリプトで実物を読めば、args が配列として入ったかどうかは確かめられます。
環境変数が要るサーバーは --env を足します。
agy mcp add github \
--type stdio \
--env "GITHUB_TOKEN=${GITHUB_TOKEN}" \
-- npx -y @modelcontextprotocol/server-github登録できたかどうかは、その場で確認しておきます。
agy mcp list名前と種別が想定どおりに並んでいれば、ひとまず登録は通っています。私はこの list を、add とセットの動作として手に馴染ませました。書いた直後に読み返す、という当たり前の手順を、ファイルを開かずにできるようになったのが実際のところの利点です。
HTTP サーバーはヘッダーの渡し方だけ違う
リモートで動いている MCP サーバーに接続する場合は --type http を使い、認証は --header で渡します。
agy mcp add my-remote-tools \
--type http \
--header "Authorization: Bearer ${MY_MCP_TOKEN}" \
https://mcp.example.com/mcp公式ドキュメントでは、リモートの MCP サーバーは Streamable HTTP で動いている必要があり、ファイル上では serverUrl(url でも可)というキーに入ります。URL は必ずスキームから書きます。mcp.example.com/mcp のようにホストから書いた設定は、握手のタイミングまで失敗が表に出ません。
そして、ここが本記事でいちばんお伝えしたい注意点です。${MY_MCP_TOKEN} はシェルが展開してからコマンドに渡すので、ファイルには展開後のトークンそのものが書き込まれます。公式ドキュメントの項目一覧を見るかぎり、mcp_config.json の中で環境変数を参照する書き方は用意されていません。シェルの履歴に実物を残さない効果はありますが、ファイルの側は守れないのです。
書いた直後に中身を確かめる
コマンドに任せても、最終的に読み込まれるのはファイルの実物です。そこで、登録内容を一覧にするスクリプトを1本置いています。何を解決するかというと、「list には出ているのに動かない」ときに、引数の形・URL の形・停止状態・秘密の露出をまとめて目で確かめられるようにすることです。
#!/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)なぜこう書いているかを三点だけ補足します。
- 1.1.24 以降はコメントと末尾カンマが許されるので、標準の
jsonで読む前に、文字列の中は触らずに それらを落としています。URL に含まれる//を消してしまわないためです - トークンや環境変数の値は先頭4文字と長さだけを出します。画面共有やログに貼っても実物が漏れません
- 問題が1件でもあれば終了コード 1 を返すので、移植スクリプトの最後に置けば、壊れた構成のまま作業を続けることを防げます
Ubuntu の Python 3.10.12 で、わざと崩した設定ファイルを読ませた出力が次のとおりです。
== 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 件閉じ括弧を落としたファイルでは ❌ JSON として読めません: Expecting ',' delimiter(1 行 35 列付近) と出て、やはり終了コード 1 で止まります。
切り分けは remove ではなく disable で行う
mcp サブコマンドで地味に効いたのが disable でした。
MCP サーバーの調子がおかしいとき、以前は設定ファイルから該当ブロックを切り取って別の場所に退避し、確認が終わったら戻す、という操作をしていました。切り取った断片をどこに置いたか忘れると、そのまま消えます。
agy mcp disable heavy-indexer # 定義は残したまま読み込みから外す
agy mcp list # 状態を確認する
agy mcp enable heavy-indexer # 元に戻す公式ドキュメントの項目一覧には disabled(既定は false)があり、true のときは設定を残したまま接続だけを止める、と説明されています。上のスクリプトで [停止中] と出るのは、この項目を読んでいるからです。完全に不要になったものだけ agy mcp remove <name> で消せば十分です。
私自身、起動が重いと感じたときに真っ先に疑うのは、いちばん最近足したサーバーではなく、いちばん重い処理を抱えているサーバーのほうでした。疑う順番を変えられるようになったのは、外して戻す操作が軽くなったからです。
なお、同じ 1.1.16 では /mcp パネルでサーバーを切り替えたときに enabledTools・timeoutSeconds・url・tools.eager が消える不具合も直っています。それより前の版でパネルから切り替えたことがあるなら、手で足した項目が残っているかを一度確かめておくと安心です。
うまく動かないときの切り分け表
コマンドで登録したのに期待どおりにならないとき、私は次の順で確かめています。
| 症状 | 原因の候補 | 確かめ方 | 直し方 |
|---|---|---|---|
list に出るのにツールが見えない | サーバーは登録済みだが disabled のまま | スクリプトで [停止中] になっていないか | agy mcp enable <name> |
| プロジェクトで足したはずのサーバーが出ない | グローバルに入れたつもりがワークスペース側を見ていた、またはその逆 | 二つのファイルをスクリプトに渡して見比べる | 共有したいものはグローバル、固有のものは .agents/mcp_config.json へ |
| stdio サーバーが起動直後に落ちる | args が1本の文字列になっている | スクリプトの「args が配列ではありません」 | 削除して --help の並びで登録し直す |
| リモートの握手が返らない | URL にスキームがない、または Streamable HTTP ではない | スクリプトの URL チェックと、サーバー側の対応方式 | スキーム(https)から書いて登録し直す |
| 認証エラーが続く | ヘッダーやトークンが古い・空のまま展開された | マスク表示の文字数が想定と合うか(空なら短くなる) | 変数を設定してから登録し直す |
| すべてのサーバーが消えた | ファイル全体の構造が崩れている | 「JSON として読めません」と行・列 | 示された位置の括弧を直す |
構成をスクリプトにして次の環境へ運ぶ
ここまでの操作がコマンドになったことで、構成そのものをシェルスクリプトとして持ち歩けるようになりました。私は次のような形で1本にまとめ、最後に先ほどの確認スクリプトを流しています。
#!/usr/bin/env bash
# mcp-bootstrap.sh — 新しい環境に MCP 構成を再現する
set -euo pipefail
: "${GITHUB_TOKEN:?GITHUB_TOKEN を設定してください}"
# 既存の同名エントリがあっても止まらないようにする
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 を挟んでいるのは、同じスクリプトを何度流しても結果が同じになるようにするためです。移植の途中で中断して流し直す、という状況が現実には起きます。
秘密の値はスクリプトに書かず、実行時の環境変数から受け取ります。冒頭の : を使ったチェックで、未設定のまま最後まで走って中途半端な構成が残る事態を防いでいます。この「サインインに頼らず環境変数で資格情報を渡す」考え方は、Antigravity CLI 1.1.13 の GEMINI_API_KEY 直接認証をサインイン不可の環境で使うでも同じ形を取りました。
よくある誤解
「コマンドで管理するなら、設定ファイルはもう気にしなくてよい」——入口が変わっただけで、書き込み先は同じファイルです。バックアップの対象からは外せませんし、フラグにない enabledTools や oauth は、いまも手で書きます。
「disable と remove は、どちらも読み込まれなくなるだけで同じ」——disable は disabled: true を立てて定義を残し、remove は定義そのものを消します。切り分けの途中で remove を使うと、戻すときに引数を思い出す作業が待っています。
「変数で渡せば、トークンはファイルに残らない」——先ほど書いたとおり、展開後の値が保存されます。守るべきなのはファイルの権限と置き場所です。
私がつまずいた場面と、いまの線引き
最初にこのメモをまとめたとき、私は --header "Authorization: Bearer ${MY_MCP_TOKEN}" と書けば、トークンの実物はどこにも残らないと思い込んでいました。履歴に残らないことと、ファイルに残らないことを、同じものとして扱っていたのです。
気づいたのは、移植のたびに確認スクリプトで中身を一覧にするようになってからでした。マスクされた header の文字数が、どう見ても変数名ではなくトークンの長さだったのです。手で JSON を書かなくなったぶん、ファイルの中身を想像で済ませていたのだと思います。
いまは、入口はコマンドに、確認はファイルの実物で と決めています。グローバルの設定ファイルは chmod 600 にして、同期フォルダやリポジトリには置きません。ワークスペースの .agents/mcp_config.json はリポジトリに入りやすい場所なので、トークンを書く項目は持たせないようにしています。
次に詰まる一歩
コマンドでの登録に慣れると、次に当たりやすいのはワークスペース側の設定です。プロジェクト直下のファイルが見つかったとログに出るのに、サーバーが起動しないという報告があり、プロジェクト直下の mcp_config.json が読まれているのに MCP が立ち上がらない — プローブ 1 本で確かめるで、起動の有無を外から確かめる方法をまとめました。
もう一つはプラグインとの名前の重なりです。CLI 1.2.2 以降、プラグインに同梱された MCP サーバーは <plugin>_<server> という名前に自動で付け替えられ、自分で登録したサーバーとはぶつからなくなりました。list やツール名に見慣れない接頭辞が付いていたら、それはプラグイン由来です。プラグインを入れる前に何を見ておくかは、Marketplace のパートナープラグインを入れる前に、導入ページで確かめる三つのことに書き残しています。
次にやること
まず agy mcp list を一度実行し、続けて上の確認スクリプトをグローバルの設定ファイルに対して流してみていただければと思います。権限の警告や、名前を思い出せないサーバーが出てくれば、そこが最初に整理する場所です。
私もまだ運び方を試している途中ですが、手で JSON を書き写す作業が減っただけで、環境を作り直すことへの心理的な抵抗がずいぶん軽くなりました。この確認の一手間だけは、急いでいる日でも省かないようにしています。