結論から言う。MCPが使えないときの原因は、/mcp に出ている状態を見れば、ほぼ「設定ファイルが読まれていない」「承認が通っていない」「プロセスが起動していない」「認証が切れている」「繋がっているがツールが空」の5つに割れる。全部を一度に疑う必要はない。
厄介なのは、これらが同じ「使えない」という体験になることだ。サーバー名すら出てこないのは設定ファイルの置き場所の問題で、名前は出るがツールが0個なのは起動後の問題で、前者に効く対処は後者にはまったく効かない。しかも claude mcp add は設定を書き込めた時点で Added ... と返すので、追加が成功したことと繋がったことは別だ。
以下は、状態の読み方から、設定ファイル、承認、stdioの起動、認証、ツールの空振り、タイムアウトまでを、実際に触る順に並べたものだ。数字や挙動は公式ドキュメントの記載に合わせている。
この記事の要点
- まず
/mcpを開く：状態がそのまま原因の分岐になる。⏸ Pending approvalは承認、✘ Failed to connectは接続、! Needs authenticationは認証、ツール0個は起動後の問題。 claude mcp addのAdded ...は「設定を書けた」の意味：接続できたかはclaude mcp get <name>か/mcpで別に確認する。- プロジェクトの設定は
.mcp.json、置き場所はリポジトリ直下：.claude/の下でも、settings.jsonのmcpServersキーでもない。VS Code形式のserversキーも読まれない。 .mcp.jsonのサーバーは一度だけ承認が要る：プロンプトを閉じたままだと⏸ Pending approvalで止まり続ける。- stdioが起動しない原因で多いのは相対パス：
commandとargsの相対パスは、.mcp.jsonの場所ではなく起動したディレクトリから解決される。 - リモートの
urlとheadersでは一部の認証系変数が空として読まれる：Bearer ${ANTHROPIC_AUTH_TOKEN}は空のまま送られ、401になり、接続失敗として表示される。 - 繋がっているのにツールが0個なら、まず
/mcpの Reconnect：それでも0ならclaude --debug=mcpでサーバーのstderrを読む。 - stdioサーバーは自動再接続されない：自動再接続はリモートサーバーだけの仕組みで、ローカルプロセスは対象外。
- 対象読者：MCPサーバーを登録したのにClaude Codeで使えない開発者、チームに
.mcp.jsonを配って「自分の環境では出ない」と言われた担当者。 - 今日やること：
/mcpを開いて、問題のサーバーがどの状態で止まっているかを1つだけ確定させる。
手順1｜まず /mcp でどの状態で止まっているかを読む
切り分けの入口はここしかない。セッション内なら /mcp、シェルからなら claude mcp list と claude mcp get <name> で、設定済みの各サーバーに状態が付く。
接続を試した結果を表す状態
✔ Connected：接続できている。ツール数が0でないかは手順6で見る。! Needs authentication：接続はできるが認証が要る。手順5へ。✘ Failed to connect：接続そのものが失敗した。この状態は「一覧コマンドが失敗した」という意味ではなく、そのサーバーに繋げなかったという意味だ。
✘ Failed to connect のときは、claude mcp list が失敗の詳細を同じ行の末尾に付け、claude mcp get <name> は Issue: の行に出す。HTTPのステータスか、エラーコードと、サーバーが返したエラー本文が入る。Claude Codeはこの詳細から資格情報らしき文字列を伏せ、展開後のサーバーURL（秘密を含みうる）は含めない。✘ Connection error という状態のときは詳細が付かない。そこに出す例外本文がURLを埋め込みうるからだ。なおこの詳細表示は v2.1.219以降で、それ以前は状態だけが出ていた（各状態と Issue: 行の仕様はAnthropic「Connect Claude Code to tools via MCP」の記載）。
接続を試していない状態
次の3つは、接続を試した結果ではなく設定上の判断を表す。Claude Codeはサーバーに繋がずにこれを出す。
⏸ Pending approval (runclaudeto approve)：.mcp.jsonのプロジェクトスコープのサーバーで、まだ承認していない。claude mcp listとclaude mcp get <name>の両方に出る。手順3へ。✘ Rejected (see disabledMcpjsonServers in settings)：disabledMcpjsonServersの指定で拒否されている。claude mcp get <name>にだけ出る。⊘ Disabled for this project (re-enable via /mcp)：そのプロジェクトのdisabledMcpServersに名前が入っている。/mcpのパネルから戻せる。v2.1.238より前は、無効化されたサーバーにも接続して健全性を確かめていたので、この表示の意味が違っていた。
url が空のリモートサーバーは not configured と出て、接続自体が行われない。詳細画面は No URL configured for this server と表示する。プラグインが「あとで設定するコネクタ」の枠だけを置いている場合があるための扱いで、v2.1.208より前は設定エラーとして再接続を促していた。
一覧に出てこないサーバー
WebSocketサーバーは claude mcp list の出力に現れない。claude mcp get <name> か /mcp パネルで確認する。ここで「登録したはずなのに一覧にない」と判断してしまうと、存在しない設定ミスを探すことになる。
MCPそのものの仕組みから確認したい場合は、Claude Code MCP実践ガイド｜設定から自作までに登録の3経路がまとまっている。
手順2｜設定ファイルの置き場所とキー名を直す
/mcp にサーバー名すら出てこないなら、接続以前に設定が読まれていない。ここで間違えやすい場所は決まっている。
読まれる場所と、読まれない場所
プロジェクトで共有するMCP設定は、リポジトリのルートに置いた .mcp.json で、サーバーは mcpServers キーの下に書く。公式ドキュメントが「MCPサーバーが読み込まれない」の原因として挙げているのは次の2つだ（Anthropic「Debug your configuration」）。
- ファイルが
.claude/の下にある。 - サーバーがトップレベルの
serversキーの下にある（VS Codeのmcp.jsonの形式）。
もう1つよくあるのが、settings.json に mcpServers を書いてしまうパターンだ。settings.json は mcpServers キーを読まない。プロジェクト共有なら .mcp.json、自分の全プロジェクトで使うなら claude mcp add --scope user を使う。
{
"mcpServers": {
"example": {
"command": "npx",
"args": ["-y", "@example/mcp-server"]
}
}
}
別のクライアント向けの手順書から持ってくるとき
MCPサーバーはClaude Code専用ではないので、Claude DesktopやCursor向けに書かれた手順書には claude mcp add のコマンドが載っていないことがある。mcpServers ブロックを渡すときは、ラッパーキーではなく中身のオブジェクトを claude mcp add-json に渡す。そのうえで、次の2つは直してから渡す。
typeのないurlエントリ："type": "http"、"sse"、"ws"のいずれかを足す。typeがないエントリをClaude Codeはstdioサーバーとして読むので、URLだけのエントリは失敗する。- 英数字・ハイフン・アンダースコア以外の文字を含むキー：その文字が使えないので、サーバー名を付け直す。
.mcp.json そのものが読めないとき
claude mcp add --scope project や claude mcp remove が次のエラーで止まることがある。
Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.
カレントディレクトリの .mcp.json が通常ファイルでないか、メッセージが示すバイト数の上限を超えている場合だ（文言と条件はAnthropic「Error reference」の記載）。通常のJSONファイルに置き換えるか削除する。v2.1.257より前は、.mcp.json がFIFOだとコマンドが無反応のまま待ち続け、/dev/zero へのシンボリックリンクだとメモリを食い続けてプロセスが落ちていたので、古い版でこの症状が出ているなら更新が先だ。
隠れた空白と予約名
設定値の先頭や末尾に見えない空白が混ざっていると、Claude Codeは警告を出す。チェック対象は command、url、args の各要素、env と headers の値とキー名で、Leading or trailing whitespace in: headers.Authorization のように該当フィールド名だけを挙げる（値は表示しない）。Claude Codeは空白を自分で取り除かず、書かれたまま使うので、設定側を直す必要がある。トークンを貼り付けたときの改行が典型だ。
サーバー名にも予約がある。workspace、claude-in-chrome、computer-use、Claude Preview、Claude Browser は組み込みサーバーの名前で、同名の定義は読み込み時にスキップされ、改名を促す警告が出る。claude mcp add は予約名をエラーで弾く。v2.1.205より前は Claude Browser が予約されていなかったので、古い設定が残っていると挙動が変わる。
手順3｜プロジェクトスコープの承認とフォルダの信頼を通す
⏸ Pending approval で止まっている場合、設定は正しい。承認の1手間が残っているだけだ。ただし「承認したはずなのに戻る」ケースがあり、そこはフォルダの信頼が絡む。
承認はセッション内から行う
.mcp.json のプロジェクトスコープのサーバーは一度だけ承認が要る。プロンプトを閉じてしまった場合、そのサーバーは無効のままなので、claude を対話で起動して /mcp から承認する。claude mcp list の ⏸ Pending approval (runclaudeto approve) は、まさにこれを促している。
クローンしたリポジトリは自分自身を承認できない
v2.1.196以降、claude mcp list と claude mcp get は、リポジトリにコミットされていない設定ファイルからの .mcp.json 承認だけを読む。しかもそれは、そのワークスペースでいちど claude を起動し、信頼のダイアログを受け入れたあとの話になる。
つまり、プロジェクトの .claude/settings.json にコミットされた enableAllProjectMcpServers や enabledMcpjsonServers は、信頼していないフォルダでは無視される。サーバーは接続も健全性チェックもされず ⏸ Pending approval のまま残る。クローンしてすぐCIやスクリプトから叩いた場合に、これで詰まる。
信頼していないフォルダでも効く承認元は次の3つだ。
- 自分のユーザー設定
~/.claude/settings.json - 管理設定（managed settings）
--settingsで渡した設定
.claude/settings.local.json（gitの追跡外）からの承認も適用されるが、Claude Codeは追跡されているかをgitで確認し、その確認は信頼済みフォルダでしか走らない。一度も信頼していないフォルダでは、信頼ダイアログを待つ。例外は自分の設定ホーム（ホームディレクトリ、または CLAUDE_CONFIG_DIR で指定した .claude を持つディレクトリ）だ。v2.1.207より前は、追跡外の .claude/settings.local.json の承認を、信頼していないフォルダでも適用していた。
なお disabledMcpjsonServers の指定は、どの設定ファイルにあってもサーバーを拒否する。承認を足しても、こちらが残っていれば通らない。
組織のポリシーで止められている場合
/mcp で Reconnect を選んだり、無効化したサーバーを戻したりしたときに次が出るなら、MCPサーバーを制限する設定に当たっている。
MCP server <name> is blocked by enterprise managed policy
原因になりうる設定は4つある。自分の ~/.claude/settings.json やプロジェクトの .claude/settings.json にある deniedMcpServers の該当エントリ、サーバーが載っていない allowedMcpServers のリスト、mcp をロックした strictPluginOnlyCustomization（~/.claude.json と .mcp.json で設定したサーバーを止める）、そしてclaude.aiコネクタに対する disableClaudeAiConnectors だ（この4つと文言はAnthropic「Error reference」の記載）。自分の設定に心当たりがないなら、どの管理設定が塞いでいるかを管理者に確認するしかない。組織としての配布と統制の設計は、Claude Code管理MCP配布｜7手順で整理している。
手順4｜stdioサーバーが起動しないときに見る4点
ローカルプロセスとして動くstdioサーバーが ✘ Failed to connect になる場合、見る順番はだいたい決まっている。
相対パスをやめる
公式ドキュメントが「起動に失敗する頻出原因」として名指ししているのがこれだ。command や args に書いた相対パスは、.mcp.json の場所ではなく、Claude Codeを起動したディレクトリを基準に解決される（Anthropic「Debug your configuration」）。だからリポジトリのルートで起動したときだけ動き、サブディレクトリから起動すると落ちる、という症状になる。ローカルのスクリプトは絶対パスで書く。PATH に載っている実行ファイルは名前だけで構わない。
-- の位置を直す
claude mcp add でstdioサーバーを追加するとき、--（ダブルダッシュ）がClaude Code自身のオプションと、サーバーを起動するコマンドを分ける。-- の後ろはそのままサーバーに渡される。
# npx server を実行する
claude mcp add --transport stdio myserver -- npx server
# KEY=value を環境に入れて python server.py --port 8080 を実行する
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080
-- がないと、Claude Codeは上の --port のようなサーバー側のフラグを自分のオプションとして読もうとする。もう1つ、--env は複数の KEY=value を受け取るので、サーバー名を --env の直後に置くと、名前を次のペアとして読んで弾かれる。--env と名前のあいだに --transport stdio などを挟む。
環境変数の参照が展開されているか確かめる
.mcp.json では ${VAR} と ${VAR:-default} が使える。展開されるのは command、args、env、url、headers の5か所だ（Anthropic「Connect Claude Code to tools via MCP」）。参照した変数が未設定で既定値もない場合、設定は読み込みに失敗せず、${VAR} の文字列がそのまま使われたうえで、claude mcp list と /mcp に不足している変数名の警告が出る。起動コマンドのパスがこれだと、存在しないパスを実行しようとして落ちる。変数を設定するか :-default を足す。
サーバーのstderrを読む
ここまでで決まらない場合は、サーバー自身が出しているエラーを読む。claude --debug=mcp で起動し、~/.claude/debug/<session-id>.txt のデバッグログにあるそのサーバーのstderrを見る。Playwright MCPのようにブラウザを起動する種類のサーバーでは、この段で依存関係の不足が見つかることが多い（実運用の例はClaude Code×Playwright MCP連携｜E2Eテスト7手順にまとめている）。
MCPサーバー側を自分で書いている場合は、MCP公式の「Build an MCP server」が最小実装の形を示している。
手順5｜リモートサーバーの認証で止まるときの読み分け
! Needs authentication や、ツール呼び出しの途中で出る認証エラーは、メッセージの文言で原因が分かれる。同じ「再認証してください」に見えて、直す場所が違う。
メッセージ3種の読み分け
セッションの途中でリモートMCPサーバーが資格情報を拒否すると、そのツール呼び出しは失敗し、/mcp でサーバーが認証待ちになる。文言は資格情報の出どころで変わる（3種の文言はAnthropic「Error reference」の記載）。
- Claude Codeからサインインするサーバー（claude.aiコネクタ含む）：
MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)。/mcpでサーバーを選び、そのメニューからサインインし直す。 headersHelperスクリプトを設定したサーバー：MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)。この表示が出る時点で、Claude Codeはヘルパーを再実行して1回リトライ済みだ。ヘルパーが返す資格情報のほうを直す。- 設定に静的な
Authorizationヘッダーを書いたサーバー：MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)。設定側のヘッダー値を更新して/mcpから再接続する。
v2.1.273より前は、この3つがすべて MCP server "<name>" requires re-authorization (token expired) という同じ文言だったので、古い版では切り分けができない。
スコープが足りないと言われる場合
サーバーがHTTP 403の insufficient_scope でツール呼び出しを拒否すると、必要なスコープ名を含むメッセージが出る。
MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate
自分のトークンにすでに載っているスコープを要求されることもある。サーバーの設定が oauth.scopes も authServerMetadataUrl も持たない場合、Claude Codeはサーバーが名指ししたスコープを要求する。どちらかを設定している場合は、その設定側のスコープを要求する。oauth.scopes を固定しているなら、足りないスコープをそのリストに足してから認証し直す。v2.1.274より前はこのケースが「サインインし直してください」の文言で出ていた。OAuthスコープを最小権限で配る設計はMCP認証をClaude Codeで安全にチーム配布で扱っている。
認証情報を書いたのに空で送られている場合
これは気づきにくい。リモートサーバーの url と headers では、一部の資格情報系の変数が展開されず、空として読まれる（Anthropic「Connect Claude Code to tools via MCP」）。プロジェクトの .mcp.json やプラグインが、あなたのClaude Codeやクラウドプロバイダの資格情報を勝手に外部サーバーへ送らないための仕組みだ。
Bearer ${ANTHROPIC_AUTH_TOKEN} と書くと、サーバーには資格情報のない Bearer が届き、たいてい401で拒否され、Claude Codeはそれを接続失敗として表示する。対象になる名前は、ANTHROPIC_API_KEY や ANTHROPIC_AUTH_TOKEN といったClaude Code自身の資格情報、AWS_BEARER_TOKEN_BEDROCK のようなクラウドプロバイダの資格情報、HTTPS_PROXY や NPM_TOKEN のように環境が持つその他の資格情報だ。この名前は設定していてもいなくても空として読まれ、:-default のフォールバックも無視される。
API_KEY のように対象外の名前は書いたとおりに展開される。対象の資格情報をサーバーに渡したいなら、自分で決めた名前の変数にコピーして、そちらを参照する。なお ANTHROPIC_BASE_URL のようなプロバイダのベースURLは展開されるので、"url": "${ANTHROPIC_BASE_URL}/mcp" は機能する（URLの値自体がユーザー名とパスワードを埋め込んでいる場合を除く）。
対象の変数を設定した状態で参照していると、Claude Codeはデバッグログにその名前を書く。claude --debug-file /tmp/claude-debug.log で起動して、ファイル内を never expanded toward a remote server で検索すれば見つかる。
Anthropicがホストするコネクタの場合
microsoft365.mcp.claude.com、gmail.mcp.claude.com、gcal.mcp.claude.com のようなホストは、第三者のIDプロバイダ経由で認証する。Claude Codeは /mcp からも claude mcp login からも、これらに対してローカルのOAuthフローを開始しない。サインインがclaude.ai側でしか成立しないためで、次のように案内される。
"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.
この場合は claude mcp remove <name> で自分のエントリを消してから、Claude Codeで使っているのと同じアカウントでclaude.ai側のコネクタを繋ぐ。自分のエントリを残したままだと、同じURLのコネクタを隠してしまう。
サーバー側ではなくネットワークの手前で止まっている可能性があるなら、Claude Codeのプロキシ設定7手順｜繋がらない時のほうが近い。
手順6｜繋がっているのにツールが出てこないとき
✔ Connected なのにClaudeがそのサーバーのツールを使わない、というケースがある。ここは原因が3層に分かれる。
ツール数が0のとき
/mcp パネルは接続済みの各サーバーの横にツール数を出し、「toolsケイパビリティを持つと宣言しているのにツールを出していないサーバー」を目立たせる。起動には成功しているがツール一覧を返していない状態だ。まず /mcp から Reconnect を選ぶ。それでも0のままなら、claude --debug=mcp を実行して ~/.claude/debug/<session-id>.txt にあるそのサーバーのstderrを読む（Anthropic「Debug your configuration」）。
cached と出ているとき
以前使ったことのあるリモートHTTP/SSEサーバーは、cached 2h ago · connects on first use · 5 tools のような表示になることがある。起動時に接続する代わりに、前のセッションで保存した探索キャッシュからツール一覧を読み込んだ状態で、実際の接続はClaudeがそのサーバーのツールを最初に呼んだときに行われる。ツールは最初のメッセージから使えるので、これ自体は何もしなくてよい。
この表示とキャッシュは v2.1.221以降の機能で、既定では無効（アカウント単位の段階的な有効化がある場合を除く）。MCP_DISCOVERY_CACHE=1 で有効化、0 で無効化できる。v2.1.238より前は既定で有効だった（探索キャッシュの仕様はAnthropic「Connect Claude Code to tools via MCP」）。なお cached のサーバーで Reconnect を選ぶと、その場で接続したうえでキャッシュのエントリは保持される。接続済みまたは失敗のサーバーで選ぶと、再接続に加えてエントリを破棄する。
ツールがAPI側で弾かれているとき
入力スキーマがAPIのJSON Schema検証に通らないツールは、Claude Codeがサーバーのツールを読み込む時点で除外する。だから通常はリクエストに混ざらない。ただし、機能フラグの取得が無効な環境や、フラグがまだ届いていないマシンでは、どのツールが弾かれるかをサーバーのログに記録したうえで送ってしまうため、次のエラーが出ることがある。
API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
tools. の後ろの数字はリクエスト内のツールの位置で、名前ではない。この除外のチェックは v2.1.216以降なので、それより古ければ claude update が先だ（Anthropic「Error reference」）。v2.1.216以降ならサーバーごとのログに該当ツールの行が出る。名指しできるログが無ければ、サーバーを1つずつ無効化して絞る。
出力が大きすぎるとき
ツールは動いているのに結果が会話に入ってこない場合、出力の上限に当たっている可能性がある。Claude CodeはMCPツールの出力が一定のトークン数を超えると警告を出し、そのうえで既定の上限がある（しきい値と既定値はAnthropic「Connect Claude Code to tools via MCP」の記載）。上限を超えた結果（画像を含まないもの）はファイルに保存され、会話にはそのパスを示すメッセージが入る。ファイルは ~/.claude/projects/ 配下、そのセッションの tool-results ディレクトリに置かれる。上限は MAX_MCP_OUTPUT_TOKENS で引き上げられる（警告のしきい値は固定）。
export MAX_MCP_OUTPUT_TOKENS=50000
claude
失敗がClaudeに伝わるかどうか
接続に失敗したサーバーのことをClaudeに伝えるかどうかは、既定で有効なツール検索（tool search）の有無で変わる。ツール検索がある構成では、どのサーバーがどんな接続エラーで失敗したかをClaudeに伝えるので、Claudeが応答の中で接続失敗を報告する。ツール検索がない構成では、失敗したサーバーの接続をClaudeに伝えない。「Claudeが何も言わないから繋がっているはず」とは判断できない。
プロトコル側の改定が影響しているかを確認したい場合は、MCP新仕様7/28対応ガイド｜既存サーバー改修要否に破壊的変更の一覧がある。
手順7｜タイムアウトと自動再接続の効き方を知っておく
「たまに繋がらない」「長い処理の途中で落ちる」はここで決まる。タイマーが複数あるので、どれに当たったのかを分けて考える。この節の既定値・環境変数・リトライ回数はAnthropic「Connect Claude Code to tools via MCP」の記載に合わせている。
起動時の接続タイムアウト
サーバーごとの接続タイムアウトには既定値があり、MCP_TIMEOUT 環境変数（ミリ秒）で変えられる（Anthropic「Connect Claude Code to tools via MCP」）。MCP_TIMEOUT=10000 claude なら10秒だ。起動の遅いサーバーで取りこぼしているなら、ここを上げる。非対話実行で --permission-prompt-tool に渡したツールが見つからないエラーが出る場合も、Claude Codeは最初の許可判断までこの既定のあいだだけサーバーの接続を待つ（v2.1.206より前は待たなかったため、健全だが起動の遅いサーバーでも同じエラーになっていた。詳細はAnthropic「Error reference」）。
ツール1回あたりの上限
ツール実行のタイムアウトは、サーバーごとに .mcp.json のエントリへ timeout フィールド（ミリ秒）を足して設定する（Anthropic「Connect Claude Code to tools via MCP」）。"timeout": 600000 なら10分だ。これはそのサーバーについて MCP_TOOL_TIMEOUT 環境変数を上書きする。
この timeout は1回のツール呼び出しに対する実時間の上限で、サーバーからの進捗通知では延びない。小さすぎる値は無視され、MCP_TOOL_TIMEOUT か、それが未設定ならドキュメント記載の既定値に落ちる。HTTP・SSE・claude.aiコネクタのサーバーには、リクエストごとにサーバーの最初の応答バイトまでを見る別のタイマーもある。Claude Codeはそれを「ドキュメントが示す最小の待ち時間」「そのサーバーに適用されるツールタイムアウト」「MCP_TIMEOUT」の3つのうち最大の値に設定する。未設定の MCP_TOOL_TIMEOUT の既定値はこの比較に入らず、最小の待ち時間を下回ってタイマーが短くなることもない。stdioとWebSocketのサーバーにはこのリクエスト単位のタイマーがない。
無反応で打ち切られる場合
応答も進捗通知も一定時間ないツール呼び出しは、実時間の上限を待たずにエラーで打ち切られる。この無反応の窓は、HTTP・SSE・WebSocket・claude.aiコネクタとstdioで長さが違う（それぞれの既定値はAnthropic「Connect Claude Code to tools via MCP」）。IDEサーバーとSDKのインプロセスサーバーは対象外になる。CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT （ミリ秒）で変更でき、0 で無効化できる。v2.1.203より前はstdioがこのチェックの対象外だった。なお十分な大きさの timeout を設定したサーバーでは、その値が無反応タイムアウトの下限としても働く（v2.1.203以降）。
しばらく走り続けると背景に移る
メインの会話でのMCPツール呼び出しが一定時間を超えて走り続けると、セッションを止めずに背景タスクへ移る（v2.1.212以降。しきい値の既定はAnthropic「Connect Claude Code to tools via MCP」）。ClaudeはタスクIDをすぐ受け取って作業を続け、結果は通知として届く。タスクは /tasks に出て、そこから止められる。上限のタイマーは背景でも効き続ける。しきい値は CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS（ミリ秒）で変更でき、0 で無効化できる。サブエージェントからの呼び出しとIDEサーバーへの呼び出しは背景化されない。
落ちたときに自動で戻るか
ここは種類によってはっきり違う（回数とバックオフの詳細はAnthropic「Connect Claude Code to tools via MCP」）。
- セッション中に切れたリモートサーバー：指数バックオフで、ドキュメントが示す回数まで再接続を試す。対話セッションでは再接続中
/mcpが pending になり、試行を使い切ると failed（または要認証）になってMCP server "<name>" disconnected · open /mcp to reconnectの通知が出る。 - HTTP/SSEサーバーの初回接続：5xx応答・接続拒否・タイムアウトといった一時的なエラーならリトライする。WebSocketの初回接続はリトライしない。認証エラーとnot foundもリトライしない（設定変更が要るため）。ただし
headersHelperがAuthorizationヘッダーの唯一の供給元である場合は、毎回ヘルパーを再実行して新しい資格情報を拾える可能性があるので認証エラーでもリトライする。 - stdioサーバー：自動再接続の対象外。ローカルプロセスなので、Claude Codeは自動では繋ぎ直さない。落ちたら
/mcpから手で再接続する。
接続後の探索リクエスト（tools/list、prompts/list、resources/list）は、一時的なネットワークエラーやサーバーエラーなら短いバックオフでリトライする。認証エラー・4xx応答・リクエストタイムアウトはリトライしない。
同じ名前が複数のスコープにあるときに、どの定義が使われるか
「直したはずの設定が効かない」ときは、別のスコープに同名のサーバーが残っていることがある。同じサーバー名が複数の場所で定義されている場合、Claude Codeは優先順位がいちばん高い1つの定義だけで接続する。
優先順位と、マージされないという前提
優先順位は上から順に、ローカルスコープ、プロジェクトスコープ、ユーザースコープ、プラグインが提供するサーバー、claude.aiコネクタになる（Anthropic「Settings」）。採用された定義のエントリが丸ごと使われ、スコープをまたいでフィールドがマージされることはない。3つのスコープは名前で重複を判定し、プラグインとコネクタはエンドポイントで判定する。つまり、上位のサーバーと同じURLやコマンドを指すプラグイン／コネクタは重複として扱われる。
組織が managedMcpServers の管理設定で提供するサーバーは、これら全部より上に立つ（v2.1.259以降）。デスクトップアプリのCodeタブでローカルセッションを開いた場合は、同名のstdioサーバーが ~/.claude.json のトップレベル（ユーザースコープ）と .mcp.json の両方にあると、Codeタブは ~/.claude.json の定義を使う。
衝突の警告が出たときの片付け方
同名でエンドポイントが違う定義が複数ある場合は、claude mcp list と /mcp に衝突の警告が出る。Claude CodeはOAuthのサインインをエンドポイント単位で保存するので、あるプロジェクトで読み込まれる定義で認証しても、別の定義が読み込まれるプロジェクトでは別途サインインが要る。要らないほうは claude mcp remove <name> --scope <scope> で消す。この警告は各スコープのエンドポイントを設定に書かれたまま引用し、${VAR} の参照は展開しないので、APIキーのような解決済みの値が表示されることはない。
どこまで切り分けても原因が見えないときは、claude --safe-mode で全カスタマイズ（CLAUDE.md、スキル、プラグイン、フック、MCPサーバー、カスタムコマンドとエージェント）を無効にしたセッションを立てて、問題が消えるかどうかを見る。消えるなら、この中のどれかが原因だと確定できる。
よくある質問
claude mcp add は成功したのに /mcp に出ません
claude mcp add が返す Added ... は「設定を書き込めた」という意味で、接続できたことを保証しません。追加した直後は claude mcp get <name> か /mcp で状態を確認してください。また、WebSocketサーバーは claude mcp list の出力に現れない仕様なので、その場合は claude mcp get <name> か /mcp パネルで見ます。
自分の環境では動くのに、チームメンバーの環境で繋がりません
まず .mcp.json のサーバーには一人ひとりの承認が要ります。相手の環境で ⏸ Pending approval になっていないか確認してください。次に、相手がリポジトリをクローンしただけでまだ信頼ダイアログを通していない場合、プロジェクトにコミットした enableAllProjectMcpServers は無視されます（v2.1.196以降）。3つ目に、command や args が相対パスだと、起動したディレクトリによって解決先が変わります。
settings.json に mcpServers を書いたのに読まれません
settings.json は mcpServers キーを読みません。プロジェクトで共有するならリポジトリのルートの .mcp.json に、自分の全プロジェクトで使うなら claude mcp add --scope user で追加してください。.claude/mcp.json やVS Code形式の servers キーも読まれません。
Bearer ${ANTHROPIC_AUTH_TOKEN} と書いたのに401になります
リモートサーバーの url と headers では、Claude Code自身やクラウドプロバイダの資格情報にあたる変数が空として読まれます。:-default のフォールバックも無視されます。自分で決めた名前の変数にその値をコピーして、そちらを参照してください。claude --debug-file /tmp/claude-debug.log で起動し、ログを never expanded toward a remote server で検索すると、どの変数が該当したか分かります。
繋がっているのにツールが0個です
/mcp から Reconnect を選んでください。それでも0のままなら claude --debug=mcp で起動し、~/.claude/debug/<session-id>.txt にあるそのサーバーのstderrを読みます。サーバーが起動はしているがツール一覧を返していない状態なので、原因はサーバー側にあることが多いです。
長い処理を走らせると途中でエラーになります
3つのタイマーのどれに当たったかを分けてください。1回の呼び出しの実時間上限（サーバーごとの timeout、または MCP_TOOL_TIMEOUT）、無反応の窓（CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT で変更）、そして起動時の接続タイムアウト（MCP_TIMEOUT）です。それぞれの既定値はAnthropic「Connect Claude Code to tools via MCP」で確認できます。進捗通知では実時間の上限は延びません。
stdioサーバーが落ちても勝手に戻ってきません
仕様どおりです。自動再接続はリモートサーバーの仕組みで、stdioサーバーはローカルプロセスのため対象外です。/mcp から手で再接続してください。
MCPサーバーが増えてから動作が重くなりました
サブエージェントは親セッションのMCPツール定義をすべて引き継ぐため、最初のターンの前にコンテキストを埋めてしまうことがあります。/context でMCPツールが占めるトークン量を確認し、使っていないサーバーは /mcp disable <name> で切ってからサブエージェントを起動してください。
インストール直後から claude コマンド自体が動きません
その場合はMCP以前の問題です。Claude Codeがインストールできない原因と対処7手順のほうを先に見てください。
あわせて読みたい
運営元 Uravation よりこの事例を自社の業務で試す場合のテーマ選定・評価・本番移行の確認項目を、無料のチェックリストにまとめています。 Claude Code業務自動化PoCチェックリストを受け取る（無料）
参考・出典
- Anthropic「Connect Claude Code to tools via MCP（Claude Code Docs）」（サーバー状態の各表示と
Issue:行、.mcp.jsonのスコープと優先順位、環境変数の展開と空として読まれる資格情報、探索キャッシュ、MCP_TIMEOUTとtimeoutフィールド、無反応タイムアウト、自動背景化、自動再接続の回数、出力上限） - Anthropic「Debug your configuration（Claude Code Docs）」（
/mcpでの確認手順、相対パスによる起動失敗、ツール0個のときのclaude --debug=mcp、.mcp.jsonの置き場所とキー名、--safe-mode） - Anthropic「Error reference（Claude Code Docs）」（認証メッセージ3種と版ごとの差、
insufficient_scope、Can't read .mcp.json、blocked by enterprise managed policy、Anthropicホストのコネクタ、入力スキーマ不正、--permission-prompt-toolと接続待ち、/mcp disable <name>とサブエージェントへのMCPツール定義の引き継ぎ） - Anthropic「Troubleshooting（Claude Code Docs）」（
/mcpでのサーバー状態確認、カスタマイズを切って原因を絞る手順） - Anthropic「Settings（Claude Code Docs）」（設定ファイルのスコープと優先順位）
- Model Context Protocol「Introduction」（MCPの位置づけとクライアント／サーバーの役割）
- Model Context Protocol「Build an MCP server」（サーバー実装の最小構成）
- Model Context Protocol「Specification（revision 2026-07-28）」（プロトコル改定の内容）
- MCP TypeScript SDK 2.0 ドキュメント（v2クライアントランタイムの基盤）
- GitHub「anthropics/claude-plugins-official — mcp-server-dev」（MCPサーバー開発用の公式プラグイン）
