設定ファイルを開かずに MCP サーバーを足す — agy mcp サブコマンドで構成を持ち運ぶ

作業機を入れ替えたとき、いちばん面倒だったのが MCP サーバーの移植でした。

旧環境の設定ファイルを開き、サーバーの定義をひとつずつ新環境へ書き写す。環境変数の名前を打ち間違え、閉じ括弧をひとつ落とし、起動してツール一覧が空になって初めて気づく。個人開発でアプリと Web を行き来していると、この作業が機材の入れ替えのたびに戻ってきます。

8月20日に出た Antigravity CLI 1.1.16 で、この移植作業がコマンドになりました。mcp サブコマンドが追加され、add / remove / list / enable / disable でユーザーレベルの mcp_config.json を扱えます。--type を指定すれば stdio と HTTP のどちらも登録できます。

私はこの変更を、機能追加というより「手が滑る余地を消す変更」として受け取りました。以下、実際に構成を組み直した順にまとめます。

手で書き写していたとき、毎回やり直していたこと

移植で失敗した箇所を並べると、性質がはっきり分かれます。

失敗の形	気づくタイミング	コマンド経由なら
末尾のカンマ、閉じ括弧の抜け	起動後。全サーバーが消える	そもそも JSON を書かない
`args` を配列でなく文字列で書く	起動後。該当サーバーだけ落ちる	引数の並びから組み立てられる
サーバー名の綴り違い	ツールを呼んだとき	`list` で登録直後に確認できる
環境変数キーの打ち間違い	認証エラーとして表面化	`--env` で渡す形が揃う
HTTP サーバーの URL キーの綴り違い	握手が返らない	`--type` でスキーマが決まる

JSON として壊れた1件が他のサーバーを道連れにする挙動は、CLI 1.1.14（8月18日）以降は改善されています。無効なエントリはログへ記録して読み飛ばし、残りは読み込まれます。ただしファイル全体が JSON として読めない場合は、どのバージョンでも全滅します。パーサーが読めなければ、どの1件を捨てるべきかも決められないからです。

この「起動前に落とす」側の話は、MCP サーバーが1本も起動しない原因は、起動前の 40 行で特定できますで扱いました。今回はもう一段手前、そもそも手で書かずに済ませる側の話です。

stdio サーバーを1行で足す

いちばん使う形から見ていきます。ローカルのプロセスとして起動する stdio サーバーです。

# 名前・種別・起動コマンドを渡して登録する
agy mcp add filesystem \
  --type stdio \
  -- npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

-- より後ろが、そのまま起動コマンドと引数になります。ここが配列として解釈されるため、引数がひとつでも文字列として書いてしまう事故が起きません。

環境変数が要るサーバーは --env を足します。

agy mcp add github \
  --type stdio \
  --env GITHUB_TOKEN=YOUR_TOKEN_HERE \
  -- 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 YOUR_API_KEY" \
  https://mcp.example.com/mcp

URL は必ずスキームから書きます。example.com/mcp のようにホストだけを書いた設定は、握手のタイミングまで失敗が表に出ません。ここもコマンド経由なら、種別を明示している分だけ書き間違いに気づきやすくなります。

なお --header に載せた値は設定ファイルへ保存されます。トークンを直接書きたくない場合は、シェル側で環境変数を展開する形にしておくと、履歴やバックアップに実物が残りにくくなります。

agy mcp add my-remote-tools \
  --type http \
  --header "Authorization: Bearer ${MY_MCP_TOKEN}" \
  https://mcp.example.com/mcp

切り分けは remove ではなく disable で行う

mcp サブコマンドで地味に効いたのが disable でした。

MCP サーバーの調子がおかしいとき、これまでは設定ファイルから該当ブロックを切り取って別の場所に退避し、確認が終わったら戻す、という操作をしていました。切り取った断片をどこに置いたか忘れると、そのまま消えます。

agy mcp disable heavy-indexer   # 定義は残したまま読み込みから外す
agy mcp list                    # 状態を確認する
agy mcp enable heavy-indexer    # 元に戻す

サーバーを1本ずつ落として症状の変化を見る、という切り分けが、定義を失う心配なしにできます。完全に不要になったものだけ agy mcp remove <name> で消せば十分です。

私自身、起動が重いと感じたときに真っ先に疑うのは、いちばん最近足したサーバーではなく、いちばん重い処理を抱えているサーバーのほうでした。疑う順番を変えられるようになったのは、外して戻す操作が軽くなったからです。

構成をスクリプトにして次の環境へ運ぶ

ここまでの操作がコマンドになったことで、構成そのものをシェルスクリプトとして持ち歩けるようになりました。私は次のような形で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
 
agy mcp list

safe_add を挟んでいるのは、同じスクリプトを何度流しても結果が同じになるようにするためです。移植の途中で中断して流し直す、という状況が現実には起きます。

秘密の値はスクリプトに書かず、実行時の環境変数から受け取ります。冒頭の : を使ったチェックで、未設定のまま最後まで走って中途半端な構成が残る事態を防いでいます。この「サインインに頼らず環境変数で資格情報を渡す」考え方は、Antigravity CLI 1.1.13 の GEMINI_API_KEY 直接認証をサインイン不可の環境で使うでも同じ形を取りました。

コマンドに移しても残る注意点

便利になった一方で、把握しておくべき境界がいくつかあります。

第一に、mcp サブコマンドが扱うのはユーザーレベルの設定です。リポジトリごとに .antigravity/mcp_config.json を置いて構成を分けている場合、そちらは従来どおり別の管理になります。チームで共有する構成はリポジトリ側、自分の作業機に固有の構成はユーザーレベル、という切り分けが素直です。

第二に、設定ファイルそのものが不要になったわけではありません。コマンドは入口が変わっただけで、書き込み先は同じファイルです。バックアップの対象からは外せません。

第三に、同じ 1.1.16 で settings.json に関する修正も入りました。解析できない settings.json を既定値で上書きしてしまう問題が直り、保存を拒否した場合はファイルがバイト単位で保たれるようになっています。以前は次に何かを保存した時点で設定が黙って初期化されていたため、長く使っている環境ほど恩恵が大きい変更です。バージョンを上げる前に、この2つのファイルだけは手元に控えておくと安心できます。

次にやること

まず agy mcp list を一度実行して、いま自分の環境に何が登録されているかを目で確かめてみてください。想定より多い、あるいは名前を思い出せないサーバーが混ざっていれば、そこが最初に整理する場所です。その一覧をそのまま mcp-bootstrap.sh に書き起こせば、次の環境移行は1コマンドで終わります。

私もまだ運び方を試している途中ですが、手で JSON を書き写す作業が減っただけで、環境を作り直すことへの心理的な抵抗がずいぶん軽くなりました。お読みいただきありがとうございました。