Claude Media
MCP_SERVER_CONNECTION_BATCH_SIZEでstdio MCPの起動並列数を変える
Claude CodeMCPTips

MCP_SERVER_CONNECTION_BATCH_SIZEでstdio MCPの起動並列数を変える

Claude Codeがstdio MCPサーバーを同時に接続する数の上限(既定3)を変える環境変数です。リモート側の変数との違い、手元で確かめた動き、症状別の切り分けをまとめます。

読了目安 約11分

MCP_SERVER_CONNECTION_BATCH_SIZEとは

MCP_SERVER_CONNECTION_BATCH_SIZEは、Claude Codeが起動時にローカルのMCPサーバー(stdio)を同時に接続する数の上限を決める環境変数です。既定値は3です。

stdioサーバーは、Claude Codeが手元でコマンドを子プロセスとして起動し、標準入出力でやり取りする形式です。.mcp.jsonにこの形式のサーバーを10本並べていても、起動時に同時に接続処理へ入るのは最大3本までになります。

この変数が触るのは「同時に何本接続するか」だけです。1本あたりの待ち時間や、接続を待つかどうかは別の変数が担当します。違いは後の節で表にまとめます。

リモート側には別の変数がある

接続先がHTTPやSSEのリモートサーバーの場合は、別の変数が上限を決めます。

変数対象既定値
MCP_SERVER_CONNECTION_BATCH_SIZE対象ローカルのMCPサーバー(stdio)既定値3
MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE対象リモートのMCPサーバー(HTTP/SSE)既定値20

環境変数の一覧には、どちらも「起動時に並列で接続する最大数」と書かれています。片方だけを変えても、もう片方には影響しません。

設定方法

一時的に試すなら、シェルで値を付けて起動します。

MCP_SERVER_CONNECTION_BATCH_SIZE=6 claude

毎回の起動に適用したい場合は、settings.jsonのenvキーに書きます。値は文字列で書きます。

{
  "env": {
    "MCP_SERVER_CONNECTION_BATCH_SIZE": "6",
    "MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE": "20"
  }
}

書き込む先は、自分だけに効かせるなら~/.claude/settings.json、プロジェクトの全員に効かせるなら.claude/settings.jsonです。自分の環境だけで試したいときは、gitignore対象になる.claude/settings.local.jsonが向いています。

settings.jsonのenvは、保存すると実行中のセッションの環境にも反映されます。ただし接続は起動時に走る処理で、反映が効くのは起動時の読み取りより後の話です。変更の効果を見たいときは、claudeを起動し直してから試してください。

手元で確かめた動き

上限どおりに起動数が絞られるのかを、Claude Code v2.1.295で試しました。空のCLAUDE_CONFIG_DIRに、起動時刻を記録して40秒眠るだけのstdioサーバーを8本登録し、claude mcp listを25秒で打ち切る構成です。モデル呼び出しやネットワーク送信は伴いません。

設定起動されたサーバー数
既定(3)起動されたサーバー数3本が同時に起動、25秒間は追加なし
MCP_SERVER_CONNECTION_BATCH_SIZE=6起動されたサーバー数6本が同時に起動、25秒間は追加なし

どちらも、起動時刻の差は0.1秒以内でした。上限の数だけが一斉に立ち上がり、残りは待たされています。

サーバーは応答しない作りにしてあるので、枠が空かないまま25秒が過ぎました。応答のないサーバーが枠を握り続け、MCP_TIMEOUT(既定30秒)で打ち切られるまで次の接続が始まらない動きに見えます。1本の反応が遅いだけで、後ろのサーバーまで巻き込まれる構造です。

この観察はclaude mcp listの場合で、対話セッションの起動と同じ経路かどうかまでは確かめていません。ここで言えるのは、変数の値と同時に起動されるstdioサーバーの数が一致したことまでです。

並列数を変えると何が変わるか

上限が3で、stdioサーバーが10本ある構成を考えます。同時に接続処理へ入れるのは3本までなので、全サーバーが接続を始めるには数回に分かれます。上限を10にすれば、10本が一度に接続を始められます。

ただし、効き目がはっきり見えるのは「接続の完了を待つ場面」に限られます。Claude Codeの起動は、既定では待たない作りだからです。

  • 既定では、サーバーはバックグラウンドで接続し、接続できたものからツールが使えるようになります
  • MCP_CONNECTION_NONBLOCKING=0にすると、最初の問い合わせの前に接続を待ちます
  • alwaysLoad: trueを付けたサーバーは、キャッシュで賄える場合を除いて起動が待ちます
  • claude -pのような非対話モードでは、--input-format stream-jsonを使わない限り、まだ接続中のサーバーを最初のターンの前に待ちます

バックグラウンド接続の場合、上限を上げても対話の体感はあまり変わりません。ツールが出そろうのが早まる程度です。待つ構成では、待機の締め切りまでに接続が終わるサーバーの数に関わってきます。

待つ構成との組み合わせ方

待機の締め切りはMCP_CONNECT_TIMEOUT_MSが決めます。既定は5000ミリ秒で、MCP_CONNECTION_NONBLOCKING=0のときと、alwaysLoad: trueのサーバーに適用されます。締め切りの時点で未接続のサーバーは、待たれずにバックグラウンドで接続を続けます。

MCP_CONNECTION_NONBLOCKING=0 \
MCP_CONNECT_TIMEOUT_MS=10000 \
MCP_SERVER_CONNECTION_BATCH_SIZE=8 \
claude

この例では、起動を待つ設定にしたうえで、締め切りを10秒に延ばし、同時接続も8本に増やしています。stdioサーバーが多いほど、締め切りまでに間に合う数は並列数に左右されます。推奨値は構成ごとに違うので、/mcpの接続状況を見ながら1つずつ動かして決めるのが近道です。

接続に失敗したサーバーをまとめて再接続する手順は、/mcp reconnect allの記事にあります。

症状から探す切り分け

「MCPまわりの起動が遅い」と感じたとき、並列数が原因とは限りません。症状ごとに、最初に見る変数をまとめます。

症状最初に見るもの理由
対話の最初の入力は早いが、ツールが出そろうまで時間がかかる最初に見るものMCP_SERVER_CONNECTION_BATCH_SIZE理由バックグラウンド接続の順番待ちが長い
MCP_CONNECTION_NONBLOCKING=0にしたら起動が重くなった最初に見るものMCP_CONNECT_TIMEOUT_MS理由待機の締め切りまで起動が止まる
claude -pの最初の応答が遅い最初に見るものCLAUDE_CODE_MCP_STARTUP_WAIT_MS理由非対話モードは接続中のサーバーを待つ
特定のサーバーだけいつも未接続最初に見るものMCP_TIMEOUTとそのサーバーのコマンド理由応答しないサーバーは枠を占有する
リモートサーバーだけが遅い最初に見るものMCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE理由stdioの上限は関係しない

上の「手元で確かめた動き」で見たとおり、応答しないサーバーが1本あると、同じ枠を待つ後続が止まります。並列数を上げる前に、/mcpで失敗しているサーバーを外すか直すほうが効くことがあります。

どのサーバーが原因か分からないときは、設定を絞って切り分けられます。claude --safe-modeを使うと、プラグイン、MCPサーバー、フックをすべて無効にした状態で起動できます。遅さが消えれば、原因はカスタマイズの側にあります。

特定の設定だけで起動したいなら、--strict-mcp-configを付けて--mcp-configのサーバーだけを読み込む方法もあります。

起動まわりの変更履歴と、遅い接続が残る理由

並列数そのものの変更は更新履歴に載っていませんが、周辺の起動処理は何度か手が入っています。stdioサーバーの遅さを調べるときに、どのバージョンから挙動が違うかの目安になります。

バージョン変更の内容
v2.1.69変更の内容-pのMCP起動で、claude.aiの設定取得とローカル接続を並行させ、逐次のバッチ処理から並列プール方式へ変更
v2.1.89変更の内容-pでMCP_CONNECTION_NONBLOCKING=trueにより接続待ちを省略可能に。--mcp-configのサーバーへの接続を5秒で打ち切るよう変更
v2.1.292変更の内容新しいプロトコル確認に応じないstdioサーバーは、一度遅い接続になると7日間記憶され、旧方式で待たずに接続

v2.1.292の変更は、起動が遅いstdioサーバーに関わります。新しい版のMCPクライアントは、HTTP、stdio、claude.aiコネクタのサーバーに新しいプロトコル改訂(2026-07-28)に対応しているかを尋ねます。対応しないstdioサーバーがこの確認で待たされていた分が、7日間の記憶で省かれます。環境変数MCP_PROTOCOL_NEGOTIATIONをlegacyにすると確認自体を行わず、autoにするとstdioを含めて確認します。この変数はv2.1.221以降が対象です。

並列数を上げても変わらない遅さがあるときは、この確認待ちが混ざっていないかを疑う価値があります。自作のstdioサーバーが起動直後の問い合わせに無反応な作りだと、確認の待ち時間が接続時間に上乗せされます。

遅いサーバーを特定する手順

どのサーバーが枠を占有しているかは、サーバーを1本ずつ減らして比べると分かります。

# 疑わしいサーバーだけを外した設定ファイルで起動
claude --strict-mcp-config --mcp-config ./mcp-subset.json
 
# 並列数を1にして、1本ずつ順に接続させる
MCP_SERVER_CONNECTION_BATCH_SIZE=1 claude

並列数を1にすると、接続が1本ずつ順に走ります。/mcpで状態が変わる順番を見れば、先頭で止まっているサーバーが分かります。原因のサーバーを直すか外したら、並列数を既定の3か、手元の構成に合う値へ戻してください。

似た名前の変数との切り分け

MCPの起動まわりには、名前が似た変数が並びます。何を決める変数かは次の表のとおりです。

変数決めるもの既定値
MCP_SERVER_CONNECTION_BATCH_SIZE決めるものstdioサーバーの同時接続数の上限既定値3
MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE決めるものHTTP/SSEサーバーの同時接続数の上限既定値20
MCP_TIMEOUT決めるもの1本のサーバーの接続試行の制限時間既定値30000ミリ秒
MCP_CONNECTION_NONBLOCKING決めるもの起動時に接続を待つかどうか既定値待たない
MCP_CONNECT_TIMEOUT_MS決めるもの待つ構成での、接続バッチの待機の締め切り既定値5000ミリ秒

MCP_TIMEOUTとMCP_TOOL_TIMEOUTの違いは別の記事で扱っています。

リモートサーバーの接続自体を後回しにする仕組みには、探索キャッシュがあります。こちらは並列数ではなく、接続のタイミングを変える機能で、Claude Code v2.1.221以降が対象です。詳しくはMCP_DISCOVERY_CACHEの記事にまとめてあります。

CIやバックグラウンドセッションで使うとき

人がいない環境では、起動時の待ちが問題になりやすくなります。次の3点がそろうと、並列数の調整が効く構成になります。

  • claude -pで動かしている。非対話モードは、接続中のサーバーを最初のターンの前に待つ
  • --mcp-configでサーバーを明示して渡している。この場合の待機の締め切りは、通常より長く取られる
  • --strict-mcp-configで、それ以外のMCP設定を読まないようにしている

--strict-mcp-configの挙動は、バージョンで違います。v2.1.246より前は、読み込まないプロジェクトスコープのサーバーについても承認待ちが残り、バックグラウンドのセッションが起動で止まることがありました。v2.1.246以降は、この承認待ちが省かれます。CIの起動が承認で止まる場合は、claude --versionでこの境界を確かめてください。

stdioサーバーを多数渡す構成なら、MCP_SERVER_CONNECTION_BATCH_SIZEを渡すサーバーの本数に合わせて上げると、最初のターンまでの待ちが短くなる場合があります。待つ側の締め切りは、前の節のMCP_CONNECT_TIMEOUT_MSと合わせて見てください。

並列数を上げ下げするときの注意

値を上げると、同時に立ち上がる子プロセスが増えます。npxでパッケージを取得するサーバーを多数登録しているノートPCでは、2〜3本ずつ上げて、/mcpの状態が崩れないことを見てください。CPUやメモリへの影響は、手元で試さないと分かりません。

逆に、下げる方向の調整もできます。共有の開発マシンやリソースの限られたコンテナで、起動時に一斉にプロセスが立ち上がるのを避けたいときは、1や2にする選択肢があります。

stdioサーバーを安全に起動するための関連設定

stdioサーバーはClaude Codeが起動する子プロセスなので、環境変数を引き継ぎます。起動するサーバーの数を増やす場合は、引き継ぐ範囲も見直せます。CLAUDE_CODE_MCP_ALLOWLIST_ENVを1にすると、安全な基本環境とサーバーごとに設定したenvだけでサーバーを起動します。詳しくはCLAUDE_CODE_MCP_ALLOWLIST_ENVの記事で扱っています。

まとめ

MCP_SERVER_CONNECTION_BATCH_SIZEは、stdioサーバーの同時接続数の上限(既定3)を変えるだけの変数です。待たない起動では効き目が見えにくく、MCP_CONNECTION_NONBLOCKING=0やalwaysLoad: true、非対話モードの待機と組み合わせたときに意味を持ちます。リモートサーバーは別変数で、既定は20です。

この変数を導入したバージョンは、環境変数の一覧にも更新履歴にも書かれていません。効かないときはclaude --versionで版を確かめ、起動し直してから試してください。

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

関連する記事

Claude Code をもっと見る →