Claude Media
Claude Codeの--mcp-configと--strict-mcp-configの使い分け
Claude CodeTips

Claude Codeの--mcp-configと--strict-mcp-configの使い分け

--mcp-configは追加読み込み、--strict-mcp-configは排他読み込みです。CI実行や検証環境、managed-mcp.jsonとの組み合わせでの挙動の違いをまとめます。

読了目安 約11分

Claude Codeには、起動時にMCPサーバーの設定をJSONで読み込む--mcp-configと、その読み込みを排他的にする--strict-mcp-configという2つのフラグがあります。見た目がよく似ているうえに動作説明も短いため混同されがちですが、両者の役割はまったくの別物です。--mcp-configは既存の設定に追加する読み込み、--strict-mcp-configは既存の設定を無視して指定したものだけを使う排他読み込みです。

この違いを理解しておくと、CI環境で不要なサーバーを読み込ませない、検証用のサーバー構成だけを一時的に試す、といった場面で迷わなくなります。逆にどちらか一方だけを覚えていると、「サーバーを追加したはずなのに既存の設定まで消えた」「排他のつもりが他のサーバーも読み込まれた」といった取り違えが起きやすいところです。

--mcp-configと--strict-mcp-configの役割の違い

--mcp-configは、JSONファイルまたはJSON文字列(スペース区切りで複数指定可)からMCPサーバーの定義を読み込み、ローカル・プロジェクト・ユーザーの各スコープや.mcp.jsonなど、既存の設定に追加します。一方--strict-mcp-configは、その--mcp-configで渡したサーバー以外のMCP設定をすべて無視します。単独では意味を持たず、--mcp-configと組み合わせて使う前提のフラグです。

項目--mcp-config--strict-mcp-config
読み込み方--mcp-config既存設定に追加--strict-mcp-config--mcp-configのサーバーだけに限定(排他)
ローカル/プロジェクト/ユーザースコープの設定--mcp-configそのまま残る--strict-mcp-config無視される
プラグイン提供サーバー・claude.aiコネクタ--mcp-configそのまま残る--strict-mcp-config無視される
単独での使用--mcp-config単独で使える--strict-mcp-config--mcp-configとセットで使う
設定への永続化--mcp-configしない(その起動限り)--strict-mcp-configしない(その起動限り)

どちらのフラグも、claude mcp addやclaude mcp add-jsonのようにスコープへ書き込むわけではありません。渡したJSONはその1回の起動でだけ有効で、.mcp.jsonや~/.claude.jsonは書き換わりません。恒常的にチームで共有する設定は.mcp.jsonをコミットする方法が向いており、--mcp-configは一時的な検証やスクリプトからの実行に向いています。

使い分けの基準

場面使うフラグ理由
通常のプロジェクト作業に、追加のサーバーを一時的に足したい使うフラグ--mcp-configのみ理由既存の.mcp.jsonやユーザースコープの設定を残したまま拡張できる
CI・バッチ実行で、指定したサーバー以外を絶対に読み込ませたくない使うフラグ--mcp-config + --strict-mcp-config理由プロジェクトやユーザーの設定に依存せず、再現性のある構成で動かせる
他のMCPクライアント向けの設定を試しに動かしてみたい使うフラグ--mcp-configのみ理由スコープに登録せず、その場限りで動作確認できる
バックグラウンドセッションで承認待ちのまま止まらせたくない使うフラグ--mcp-config + --strict-mcp-config理由プロジェクトスコープのサーバーを読み込まないため、承認プロンプトの対象自体が無くなる

Clineなど他のクライアント向けに書かれたmcpServersブロックをそのまま試したいだけなら、claude mcp add-jsonでスコープに登録する前に、--mcp-configで一度読み込んで動作を確認する使い方もできます。恒久的に移行する手順はClineからClaude CodeへMCP設定を移行する手順にまとめています。

--mcp-configでサーバーを一時的に追加する

--mcp-configにはJSONファイルのパスを渡します。中身は.mcp.jsonと同じmcpServers形式です。

{
  "mcpServers": {
    "weather-api": {
      "type": "http",
      "url": "https://api.weather.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/tool-cli",
      "args": ["--mode", "readonly"]
    }
  }
}
claude --mcp-config ./mcp-servers.json

ファイルは複数渡せます。スペース区切りで並べると、それぞれのmcpServers定義がまとめて追加読み込みされます。ただし、複数ファイルに同じ名前のサーバーを定義したときにどちらが優先されるかは公式ドキュメントに明記されていません。名前の衝突を避けたいなら、ファイルを分けずに1つのJSONへまとめておくほうが安全です。

.mcp.jsonやmanaged-mcp.jsonは同じmcpServers形式で${API_KEY}のような環境変数展開に対応しており、--mcp-configに渡すファイルも同一のスキーマなので同じ書き方が使えるとみられます。CIで認証情報付きのサーバーを読み込ませるときは、トークンを直書きせず環境変数経由にしておくと、ファイルをリポジトリにコミットしても秘密情報が漏れません。

-p(--print)と組み合わせて非対話で実行する場合、Claude Codeは接続待ちのサーバーが揃うまで最初のターンの実行を待ちます。上限はMCP_TIMEOUT環境変数で、既定は30秒です。ただしツールリストがキャッシュ済みのサーバーはこの待機をスキップし、最初にそのツールが呼ばれたタイミングで接続します(この待機の挙動はv2.1.221以降)。--output-format stream-jsonで実行している場合、読み込みに失敗した--mcp-configのエントリはsystem/initイベントのmcp_server_errorsフィールドに記録されるため、スクリプト側でサーバーが読み込まれなかったことを検知できます(v2.1.219以降)。

--strict-mcp-configで既存設定を無視して起動する

claude --strict-mcp-config --mcp-config ./mcp-servers.json

このコマンドを実行すると、./mcp-servers.jsonに書いたサーバー以外は一切読み込まれません。.mcp.jsonのプロジェクトスコープのサーバーも、ユーザースコープの~/.claude.jsonのサーバーも対象外になります。

活用場面のひとつが、対話プロンプトを出せないバックグラウンドセッションです。claude -p実行やAgent SDK経由のセッション、クラウドセッションでは、.mcp.jsonのプロジェクトスコープサーバーを使う前の承認プロンプトをそもそも表示できないため、Claude Codeは確認なしでそのまま読み込みます。この挙動自体を避けて「指定したサーバー以外は読み込ませない」ようにしたいときに--strict-mcp-configを使います。同じ目的はdisabledMcpjsonServersへの登録や、--setting-sourcesでプロジェクト設定そのものを読み込み対象から外す方法でも達成できますが、--strict-mcp-configは起動コマンド1行で完結する点が扱いやすいところです。--setting-sourcesはコンマ区切りでuser・project・localを指定でき、プロジェクトスコープの設定だけを狙って外すこともできます。恒久的に特定のサーバーだけを封じたいならdisabledMcpjsonServers、その場限りで構成をまるごと固定したいなら--strict-mcp-config、というように目的で使い分けます。

読み込むサーバーを絞ることは、コンテキストに載るツール定義の数を減らすことにもつながります。MCPサーバーが増えるほどツール定義がコンテキストを圧迫する仕組みはMCPのツール定義はなぜコンテキストを圧迫するのかで扱っています。

managed-mcp.jsonがある環境では両方の挙動が変わる

組織がmanaged-mcp.jsonを配布している端末では、--mcp-configと--strict-mcp-configの扱いが変わります。managed-mcp.jsonはMCPサーバーへの排他制御用の設定で、これが配置された端末はそのファイルに書かれたサーバーとmanagedMcpServersで提供されたサーバー以外を使えなくなります。プラグイン提供のサーバーや--mcp-configで渡すサーバーも例外ではなく、ユーザー側で独自にMCPサーバーを追加・変更・利用すること自体ができなくなります。

実行環境--mcp-configを渡した場合--strict-mcp-configを渡した場合
通常のワークステーション--mcp-configを渡した場合起動時にエラーで終了する--strict-mcp-configを渡した場合起動時にエラーで終了する
セルフホストランナー上のクラウドセッション--mcp-configを渡した場合managed setのサーバーだけで起動し、--mcp-configで渡したサーバーやclaude.aiコネクタはスキップされる--strict-mcp-configを渡した場合起動時にエラーで終了する

ワークステーションで--mcp-configを渡すと、Claude CodeはYou cannot dynamically configure MCP servers when an enterprise MCP config is presentというメッセージとともに起動時に終了します。セルフホストランナーなど一部のクラウドセッションでは終了せず、managed setのサーバーだけで起動しますが、どのサーバーが除外されたかはセッション内には表示されません。除外されたサーバー名はstderrへの警告としてのみ出力され、セルフホストランナーではdebugログレベルで記録されます。

--strict-mcp-configはワークステーション・クラウドセッションのどちらでも常に起動時に終了します。このフラグは「managed setを置き換えたい」という要求そのものにあたるため、managed-mcp.jsonによる排他制御と両立しません。

よくあるつまずき

  • -p実行が起動直後に固まる: --mcp-configで指定したサーバーの接続待ちで、MCP_TIMEOUT(既定30秒)まで最初のターンが始まりません。接続に時間がかかるサーバーがあるなら、タイムアウト値を調整するか、キャッシュ対象になるHTTP/SSEサーバーに寄せると待機を避けられます。
  • --strict-mcp-configだけ付けて動かなくなる: 単独では意味を持たないフラグです。--mcp-configとセットで渡し忘れていないか確認してください。
  • シェルでのJSONエスケープ漏れ: --mcp-configにJSON文字列を直接渡す場合、シェルのクォート処理でエスケープが崩れやすいところです。複雑な設定はファイルに書いてパスを渡すほうが安全です。
  • 予約済みの名前を使って読み込まれない: Claude Codeはworkspaceやclaude-in-chrome、computer-useなどの名前をビルトインサーバー用に予約しています。--mcp-configのJSONでこれらと同じ名前を使うと、その定義は読み込み時にスキップされ警告が表示されます。読み込まれたサーバーの一覧はセッション内で/mcpを実行するか、別ターミナルからclaude mcp listで確認できます。
  • managed-mcp.json配布先で急に起動しなくなる: 組織のポリシーで配布されたmanaged-mcp.jsonがある端末では、--mcp-configはエラー終了か、一部サーバーが警告だけでスキップされる挙動になり、--strict-mcp-configは常にエラー終了になります。個人のスクリプトやローカルのclaudeコマンドのラッパーにこれらのフラグを組み込む前に、対象端末が管理対象かどうかを確認してください。
  • Claude Desktopの設定と混同する: --mcp-configはCLIの起動フラグで、Claude Desktopアプリのclaude_desktop_config.jsonとは別の仕組みです。Desktop側の設定ファイルについてはClaude Desktop MCP設定ガイドを参照してください。

まとめ

--mcp-configは既存のMCP設定に追加でサーバーを読み込むフラグ、--strict-mcp-configはその読み込みを排他的に限定するフラグです。一時的な検証や他クライアント向け設定の試し読みには--mcp-config単体で十分ですが、CIやバックグラウンドセッションのように再現性と確実な排他が必要な場面では両方を組み合わせます。組織がmanaged-mcp.jsonを配布している環境では両フラグとも起動時エラーの対象になりやすいため、CIやスクリプトに組み込む前に対象端末のポリシーを確認しておくと、想定外のジョブ失敗を防げます。どちらのフラグも設定ファイルへの永続的な書き込みはしないので、まずは手元で--mcp-config単体を試し、挙動に納得してから--strict-mcp-configを足す、という順番で試すと事故が少なくなります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →