◉ANTIGRAVITY LABEN
記事一覧/連携・プラグイン
⬡ 連携・プラグイン/2026-08-22初級

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

Antigravity CLI 1.1.16 の mcp サブコマンドで MCP サーバーを手編集なしに登録・停止する手順を、グローバルとワークスペースの設定の違い、トークンがファイルに残る落とし穴、登録内容を秘密を伏せて確かめるスクリプト、症状別の切り分け表とあわせてまとめます(2026年11月時点の公式ドキュメントで確認)。

MCP29Antigravity CLI44環境構築3設定12

作業機を入れ替えたとき、いちばん面倒だったのが 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 を書き写す作業が減っただけで、環境を作り直すことへの心理的な抵抗がずいぶん軽くなりました。この確認の一手間だけは、急いでいる日でも省かないようにしています。

シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ(¥150)で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

⬡ 連携・プラグイン2026-10-22
プロジェクト直下の mcp_config.json が読まれているのに MCP が立ち上がらない — プローブ 1 本で確かめる
Antigravity CLI のログには project-local の設定ファイルを使うと出るのに、MCP サーバーは起動しない。公式 Issue の経過(2026年11月時点で未解決)、ログの文言が約束していること、起動の有無を確かめる最小のプローブ、似た症状との切り分け表、プロジェクト別に MCP を分ける現実的な選択肢をまとめます。
⬡ 連携・プラグイン2026-10-19
Antigravity CLI に GitHub MCP を繋ぐ最初の 1 本 — 書き換えるのは url の 1 語だけでした
Antigravity CLI で GitHub MCP を使うには、設定の url を serverUrl に書き換える必要があります。公式の MCP ドキュメントを根拠に、リモート接続と Docker 接続の書き方、読み込む前の検査スクリプト、トークンの置き場所と切り分けの順番をまとめます。
⬡ 連携・プラグイン2026-08-20
MCP サーバーが1本も起動しない原因は、起動前の 60 行足らずで特定できます
設定ファイルの1件の書き間違いで MCP サーバーが揃って起動しなくなる状況を、起動前に検査する小さなスクリプトで潰す手順です。実際に壊した設定へ通した出力と、JSON の同名キーが黙って消える落とし穴まで扱います。