「設定ファイルにちゃんと書いたはずなのに、Claude CodeでMCPが認識されない」「/mcp を打っても何も出てこない」——Claude Codeを触り始めた人が、ほぼ必ず一度はぶつかる壁です。この記事では「MCP 設定 つまずき 繋がらない」で検索してたどり着いたあなたが、どこで詰まっているのかを切り分けて、最短で解決できるように整理します。
結論から言うと、繋がらない原因のほとんどは「書き方が間違っている」のではなく、記述先・スコープ・再起動・環境（特にWindows）のどれかがズレていることです。順番に潰していきましょう。
そもそもMCPとは何か：Claude Codeの「外部ツール接続口」
MCP（Model Context Protocol）は、Claude CodeがGitHubやNotion、Slack、データベースといった外部ツール・データソースと連携するための共通プロトコルです。たとえばNotion用のMCPサーバーを登録すると、Claude Codeから「このページの内容を読んで」「議事録を作って追記して」といった操作ができるようになります。
ここで初心者がつまずく第一歩が、「MCPサーバー」という言葉のイメージです。サーバーと聞くと大げさに感じますが、実態は外部ツールと話すための小さな仲介プログラムだと思ってください。これをClaude Codeに「登録」して初めて使えるようになります。逆に言えば、登録が正しく完了していなければ、いくら設定ファイルを眺めても繋がりません。
設定方法は2系統ある：ここが混乱の元
つまずきの大きな原因が、設定の入り口が複数あることです。古い記事と新しい記事で書き方がバラバラに見えるのも、このせいです。2026年時点では主に次の2つを使い分けます。
| 方法 | 書く場所 | 向いている場面 |
|---|---|---|
claude mcp add コマンド |
CLIで実行（内部で設定に書き込まれる） | 手早く登録したい・スコープを意識して入れたい |
.mcp.json |
プロジェクトのルートディレクトリ | チームでリポジトリ共有したい |
claude_desktop_config.json |
Claude Desktopアプリの設定ファイル | Desktopアプリ側で使いたい |
ここで最も多い誤解が「
claude_desktop_config.jsonに書けばClaude Code（CLI）でも動く」というもの。Desktopアプリ用とClaude Code（ターミナル）用は管理が別物です。CLIで使いたいならclaude mcp addか.mcp.jsonを使うのが基本だと覚えておきましょう。
まずはコマンドで登録するのが確実
迷ったら、設定ファイルを手書きするより claude mcp add から始めるのがおすすめです。タイポや配置場所のミスを減らせます。
# 基本構文
claude mcp add <名前> -- <実行コマンド> <引数...>
# 例：標準入出力(stdio)型のサーバーを登録
claude mcp add my-tool -- npx -y @example/mcp-server
# 登録できているか確認
claude mcp listclaude mcp list で名前が出てくれば、登録自体は成功しています。ここに出てこないなら、まだ「繋がる以前」の段階です。
チーム共有したいなら.mcp.json
リポジトリにコミットしてチーム全員で同じMCPを使いたい場合は、プロジェクトルートに .mcp.json を置きます。Notion連携を例にすると、こんな形です。
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_API_KEY": "secret_xxxxxxxxxxxx"
}
}
}
}command（実行コマンド）、args（引数）、env（APIキーなどの環境変数）の3点セットが基本構造です。APIキーが必要なツールで env を書き忘れると、登録はできても認証で弾かれて「繋がらない」状態になります。
スコープの違い：ここを間違えると「自分は動くのに他の人は動かない」
MCPには3つのスコープ（適用範囲）があります。これを理解していないと、「自分の環境では動くのにチームメンバーでは動かない」という不可解な状況に陥ります。
| スコープ | 適用範囲 | 共有されるか |
|---|---|---|
| local | 自分・そのプロジェクト内のみ | されない（個人用） |
| project | .mcp.json 経由でプロジェクト全体 |
される（チーム共有向け） |
| user | 自分の全プロジェクト | されない（横断・個人用） |
よくあるパターンが、チームで共有したいのにスコープが local のままというケース。これだと設定が自分の手元にしか残らず、他のメンバーがクローンしても何も見えません。共有したいなら --scope project を指定して .mcp.json に書き出しましょう。
claude mcp add notion --scope project -- npx -y @notionhq/notion-mcp-server「繋がらない」を原因別に切り分ける
ここからが本題です。症状ごとに対処を分けます。実際にやってみると、上から順にチェックするだけで大半は解決します。
症状1：/mcp や claude mcp list に出てこない
- 再起動したかを確認。設定を追加・変更したら、Claude Codeを一度終了して立ち上げ直す必要があります。「書いたのに出ない」の半分はこれです。
claude mcp listで登録自体を確認。CLIに出ないなら設定ファイルの配置場所か記述形式が間違っています。- 設定ファイルが正しい場所にあるか確認。
.mcp.jsonはプロジェクトのルート（Claude Codeを起動したディレクトリ）に置く必要があります。サブフォルダに置いて認識されないのが定番ミスです。 - JSONの構文エラーをチェック。末尾カンマや閉じ括弧の漏れがあると、ファイルごと無視されます。
症状2：登録はされているが起動に失敗する
/mcp でサーバー名は見えるのに「failed」と表示される場合は、実行コマンドそのものが動いていない可能性が高いです。設定に書いた command を、ターミナルで手動実行してみてください。
# 設定に書いたコマンドを単体で叩いてみる
npx -y @notionhq/notion-mcp-serverここでエラーが出るなら、Claude Codeの問題ではなくコマンドや依存パッケージ・APIキーの問題です。切り分けが一気に進みます。
症状3：長時間処理で切断される（ABNORMAL_CLOSURE / 1006）
大規模なデータ取得など時間のかかる処理で、ツールがタイムアウトして落ちることがあります。HTTP/SSE型の接続では、一時的な障害（5xxやタイムアウト）に対して最大3回まで自動再試行し、それでも失敗すると失敗状態としてマークされる仕様です。
恒常的にタイムアウトするなら、タイムアウト値を延ばす環境変数を見直しましょう。
# 例：MCPツールのタイムアウトを延長（ミリ秒指定）
export MCP_TOOL_TIMEOUT=120000
# Claude Code起動時に効かせる
MCP_TOOL_TIMEOUT=120000 claude環境変数名や挙動はバージョンで変わることがあります。2026年時点の挙動として、まずは小さなリクエストで動作を確認し、必要に応じてタイムアウトを伸ばすのが安全です。
環境別の落とし穴：特にWindows / Electron
設定が正しく見えるのに動かない場合、環境固有の問題を疑います。報告が多いのがWindowsとElectron環境でのパス解決です。
- パスの区切り文字：JSON内でWindowsのパスを書くとき、バックスラッシュは
\\とエスケープが必要です。C:\\Users\\you\\toolのように二重にします。 - コマンドの実体：Windowsでは
npxがnpx.cmdとして解決される必要がある場合があります。動かないときはcmd /c npx ...の形を試すと通ることがあります。 - 絶対パス指定：相対パスで解決できないときは、実行ファイルやスクリプトを絶対パスで書くと確実です。
よくある誤解・NGパターン
- 「mcp devで動いたから完了」：開発用の
mcp devで動いても、実際にClaude Code（やDesktop）で動くとは限りません。最終的に使う環境で/mcpを確認するまでが検証です。 - 「Desktopの設定をCLIに流用」：前述のとおり管理が別。使う側（CLIかDesktopか）に合わせて設定先を選びます。
- 「再起動せずに直ったか確認」：設定変更後の再起動は必須。これを飛ばして「直らない」と判断しがちです。
- 「APIキーを直書きしてコミット」：
.mcp.jsonをリポジトリ共有する場合、APIキーをそのまま書くと漏洩リスクがあります。環境変数経由にするなどの配慮を。
FAQ
Q. claude mcp add と .mcp.json、どっちを使えばいい？
個人で素早く使いたいなら claude mcp add、チームで共有したいなら --scope project 指定で .mcp.json に書き出す、が基本の使い分けです。
Q. /mcp を打っても無反応です
まず再起動、次に claude mcp list でCLI側の登録を確認してください。CLIにも出ないなら、設定ファイルの場所か構文に問題があります。
Q. 自分は使えるのにチームメンバーが使えません
スコープが local または user になっていないか確認を。共有には project スコープ（.mcp.jsonのコミット）が必要です。
Q. しばらくすると勝手に切断されます
長時間処理によるタイムアウトの可能性があります。MCP_TOOL_TIMEOUT などのタイムアウト設定を見直し、まず小さなリクエストで挙動を確認してください。
まとめと次の一歩
Claude CodeでMCPが「繋がらない」とき、見るべき順番はシンプルです。
- 設定したら必ず再起動する
claude mcp listで登録自体を確認する.mcp.jsonがプロジェクトルートにあるか、JSON構文は正しいか- 実行コマンドを単体で叩いて、ツール側の問題を切り分ける
- 共有が目的ならスコープを
projectに - Windowsならパスのエスケープとコマンド解決を疑う
この順で潰していけば、原因不明だった「繋がらない」が、たいてい「あ、再起動してなかった」「ルートに置いてなかった」といった具体的なミスに着地します。次の一歩としては、まずGitHubやNotionなど1つだけMCPを登録して /mcp で確認するところから始めてみてください。1つ通せば、2つ目以降は同じ手順の繰り返しです。
コメント