Claude Codeのsubagent MCPはいつ起動する？信頼と停止方法を実測

cloneしたリポジトリの .claude/agents/ にあるインラインMCPサーバーは、そのフォルダを信頼するまで起動しません。Claude Code v2.1.238からの判定で、claude -p でも同じです。信頼後は、そのsubagentの開始時、または --agent でmain sessionにした場合の起動時に接続します。起動させずに点検するならファイルを読みます。抑止するなら --strict-mcp-config を使えますが、明示した --agents は例外です。

確認日：2026-11-12 JST。対象：Claude Code 2.1.319、macOS、Node.js v26.12.1。公式文書も同日に取得しました。未ログインの隔離環境で、ダミーMCPの起動の有無を記録しました。モデルの呼び出し、対話の信頼ダイアログ、SDK、古いバージョンは試していません。

要点は、定義の出所を分けて見ることです。

• project・--add-dir のインライン定義は、定義元フォルダ自身の信頼を待ちます。
• 親フォルダの信頼と -p の自動の扱いは、この判定に数えません。
• ユーザーのagent、明示した --agents、登録済みサーバー名への参照には、このフォルダの信頼判定を適用しません。
• --bare や設定元の限定を、すべてのMCPを止める保証として扱わないでください。

#cloneしたrepoのsubagentのMCPは開いただけで起動しますか？

フォルダを開く操作と、Claude Codeでagentを動かす操作は別です。Subagentsの公式文書は、projectと --add-dir のagentファイルにあるインラインMCPを、そのフォルダの信頼後に読み込むと説明しています。今回の未信頼の実測でも起動しませんでした。

これはリポジトリのコード全体を止める仕組みではありません。たとえばsettingsのhookや .mcp.json は、別の信頼・承認規則に従います。起動前に実行対象を確認してください。

#v2.1.238で何が変わりましたか？

Changelogの2.1.238（2026-08-20）に、この信頼判定の追加があります。Subagents文書も、それ以前は信頼を確認せずに読み込んでいたと説明しています。古い挙動への不安を、そのまま現在の未信頼フォルダへ当てはめると判断を誤ります。今回は2.1.319だけを試しました。

#claude -pやSDKでは違いますか？

Permissionsの表では、-p とSDKは対話の信頼ダイアログを出しません。それでもprojectのインラインMCPに必要な信頼は省略されません。SDKの記述は文書による説明で、今回の実測は claude -p だけです。

#フォルダを信頼するといつ何が起動しますか？

公式文書では、subagentの開始時にインラインサーバーへ接続し、終了時に切断します。--agent でmain sessionにした場合は起動時です。remoteのHTTP/SSEサーバーには、キャッシュ済みなら最初のツール呼び出しまで接続を遅らせる場合があります。今回のダミーはローカルのstdioだけです。

#親フォルダを信頼していれば足りますか？

足りません。今回は、信頼なし、親だけ信頼、定義元自身を信頼、の三つを合成設定で分けました。projectと --add-dir のインライン定義は、自身を信頼した条件だけで起動しました。

#--add-dirで足したフォルダはどう扱われますか？

信頼済みworkspaceのリポジトリ外にある追加フォルダには、そのフォルダの信頼記録が必要です。今回も別のダミーフォルダで同じ結果を得ました。作業フォルダを信頼したことを、追加先への許可と読み替えないでください。

#信頼していなくても起動するのはどれですか？

次の表は抑止なしの条件です。「公式」は定義元フォルダの信頼規則、「実測」は今回のstdioの起動だけを示します。登録済み名への参照には、別途 .mcp.json を作り、-p で実行しました。

managedが供給するagentのインラインも、このフォルダの信頼を確認しないと公式文書にあります。managedの実測はしていません。信頼判定がないことは、他のポリシーも無効になるという意味ではありません。

.mcp.json の承認とは区別してください。詳細はClaude CodeのMCP設定とスコープにまとめています。

この表の対話と mcp list の説明は公式文書によります。通信を避ける点検では claude mcp list を実行せず、ファイルを読んでください。

#起動させずに中身を確かめるには？

まず .claude/agents/*.md の先頭にあるfrontmatterの mcpServers を読みます。名前だけの文字列は既存接続への参照、名前の下に command や url があるものはインライン定義です。

読み取り用の点検スクリプトも用意しました。信頼できる場所へ保存し、中身を確認してから実行してください。クローン先の同名スクリプトを使う手順ではありません。

node /trusted-tools/agent-inline-mcp-audit.mjs /path/to/cloned-repo

名前・type・command・args・urlをJSONに出します。コマンドの実行、URLへの接続、設定の書き込みは行いません。.claude.json も読みません。出力のargsやURLに秘密が含まれる可能性があるため、そのまま公開しないでください。

これは完全なYAML検証器ではありません。2スペース字下げのmapping・list・単純な値・JSON形式の配列を読む限定版です。アンカー、複数行の値などの未対応構文はエラーにし、agentファイルと対象ディレクトリのsymlink、65,536 bytesを超えるファイルも拒否します。エラーを「定義なし」と扱わず、テキストで確かめてください。ユーザーagent、plugin、再帰したディレクトリや他の実行経路は点検対象外です。

#debug logのどの行を見ればよいですか？

すでに実行したセッションのdebug logでは Skipping frontmatter MCP servers と not trusted を探します。今回のログは、隔離先の .claude.json と projects["<path>"].hasTrustDialogAccepted を示しました。ログを取るために新しく起動すると、他のMCPやhookも動く可能性があります。読むだけの点検とは区別してください。ログにも秘密が入る可能性があります。

#起動を止めるにはどうしますか？

次は定義元自身を信頼した条件の実測です。「なし」はダミーの起動がなかったという観測で、セッション全体の安全性を保証しません。

--strict-mcp-config は --mcp-config 以外の設定を除きます。ただし明示した --agents は公式に例外です。--mcp-config へ自分で渡すサーバーも点検してください。managed-mcp.jsonが配備されている環境では、strictを指定すると起動時に終了すると公式文書が説明しています。

--bare と --setting-sources user の表は、このバージョンで観測した結果です。project・追加先のagentが見つからない警告も出ており、「agentは動くがMCPだけ止まった」とは言えません。

deniedMcpServers は公式ポリシー文書の設定です。今回は隔離したユーザー設定で [{"serverName":"dummy"}] を指定すると、全出所のダミーが止まりました。名前の変更への耐性や組織のmanaged設定は未検証です。disabledMcpjsonServers は .mcp.json 向けなので、agentのインライン定義の抑止と混同しないでください。

#75条件の実測はどうでしたか？

出所5種類×信頼3種類×抑止5種類を全列挙しました。事前に期待値を定めた51条件はすべて一致し、文書だけでは組合せを決めなかった24条件は観測として残しました。起動を観測した条件は23件です。これは製品の性能や安全性のスコアではありません。

全実行の環境は未ログインで、終了コードはいずれも1でした。agent未発見で止まる条件も含みます。ダミーが起動した23条件では接続が認証エラーより前に起きたため、モデルを呼ばずにspawn・initialize・tools/listを記録できました。モデルの応答品質や実サービスへの接続成功を示す結果ではありません。

#どう再現しますか？

75条件の期待値と観測記録を保存しています。検証コードと取得原本のSHA-256はリポジトリの検証記録にも残しました。実験器は今回のMacのパスに固定しており、他の環境へそのまま実行する汎用ツールではありません。

実験はすべて env -i で環境を絞り、HOME・CLAUDE_CONFIG_DIR・CODEX_HOME・TMPDIR・XDG_CONFIG_HOME とGitの設定先をscratch配下へ向けました。macOSのsandbox-execで実の設定ディレクトリの読書きとIPへの外向き通信を拒否しました。ダミーは手元のNode.jsスクリプトで、外部パッケージを取得していません。

本物の設定を試し読みせず、同じ拒否規則を合成カナリアに当てて読み書きの失敗を確認しました。規則を外すと成功する変種も確認しました。照合器は信頼・strict・出所の区別を壊した3変種を検出し、空のmarkerを見る観測器の変種も対照の欠落として検出しました。実設定の値やハッシュは記録していません。

#確認していないことは何ですか？

信頼ダイアログの操作はせず、隔離したJSONの信頼キーで代用しました。Agentツールがsubagentを起動する経路、SDK、remote MCP、managed・plugin、Windows/Linux、古いバージョン、実サービスの認証後は未実測です。ファイルを読んだだけで、書かれたコマンドの安全性までは判定できません。

#関連記事と一次情報はどこですか？

• MCP設定の3スコープと承認
• Postmanが追加した設定を読む点検表
• 作業フォルダ外への書き込み制限
• Skillsとagentの使い分け
• Claude Codeの指示ファイル探索
• DownloadsのAGENTS.mdを調べる
• 公式CLIのフラグ、設定先の環境変数、MCPの設定、設定リファレンス

結論は、信頼の有無に加えて定義の出所と起動フラグを確かめることです。まだ実行したくないrepoでは、frontmatterの点検から始めてください。

#よくある質問は？

#cloneしたrepoのsubagentのMCPは自動で起動しますか？

projectのagentファイルにあるインラインMCPは、その定義元フォルダを信頼するまで起動しません。信頼後はsubagentの開始時、--agentでmain sessionにした場合は起動時に接続します。remoteのキャッシュ済み接続には遅延接続の例外があります。

#claude -pで実行すると信頼を飛ばしますか？

このインラインMCPの判定では飛ばしません。親フォルダだけの信頼も足りません。ただし.mcp.jsonのサーバーは-pで承認を尋ねず接続するため、二つを区別してください。

#信頼したフォルダの記録はどこにありますか？

公式文書は~/.claude.jsonのprojects["<path>"].hasTrustDialogAcceptedを示しています。今回の実験ではCLAUDE_CONFIG_DIR配下へ保存先を隔離しました。手で信頼を付ける前に、実行対象を点検してください。

#--strict-mcp-configで--agentsのインラインも止まりますか？

止まりません。公式文書が明示入力の例外とし、2.1.319の今回の実測でも起動しました。--bareでもこの明示入力は起動したので、渡す定義自体を点検してください。

#pluginのsubagentに書いたmcpServersは使われますか？

公式文書ではplugin由来のsubagentのmcpServersは無視されます。今回pluginの実測はしていません。ファイルの出所と通常のproject agentを区別してください。

#v2.1.238より前のバージョンではどうしますか？

公式文書によると、そのバージョンより前はこのフォルダの信頼を確認せずに読み込んでいました。更新後に設定と挙動を確認してください。古いバイナリの実測はしていません。