Claude CodeのMCP設定と、つながらないときの切り分け

MCPで何ができるようになるのか

Claude Codeは、そのままだと手元のファイルを扱う道具です。MCPを設定すると、そこに外部のサービスへの接続口が増えます。検索サービスからデータを取ってくる、外部に保存してある情報を読む、といったことができるようになります。

言い換えると、**手元のファイルの外に手を伸ばすための仕組み**です。ファイル整理や書類作成だけが目的なら、MCPは必須ではありません。まずMCPなしで使ってみて、外部のデータが必要になった時点で足すので十分です。

最初から全部つなごうとすると、設定でつまずいて肝心の作業に進めないことがよくあります。実際に使う1つだけを足す、という進め方をおすすめします。

設定はどこに書くのか（スコープの違い）

設定の置き場所は1つではなく、効く範囲が違います。ここを理解していないと「書いたのに読まれない」が起きます。

作業フォルダの中に置けば、そのフォルダで作業するときだけ有効です。案件ごとに違うサービスをつなぐ場合はこちらです。一方、自分の環境全体に対して設定すれば、どのフォルダで起動しても使えます。毎回使うサービスはこちらが楽です。

**「書いたのに認識されない」で最も多いのは、効く範囲が違う場所に書いていたケースです。** 案件フォルダに書いたつもりが別の階層だった、あるいは全体に設定したつもりが作業フォルダ側だった、というずれです。設定を確認するコマンドが用意されているので、まずは今どれが認識されているかを表示させてください。**書いたファイルを見直すより、認識されている一覧を見るほうが早いです。**

原因1: WindowsとMacで書き方が違う

同じ設定をそのまま持ち込むと、片方では動いて片方では動きません。ここは実際によく踏みます。

起動するコマンドの指定方法が環境によって変わるためで、Mac向けに書かれた設定をWindowsにコピーすると、その行が原因で読み込みに失敗します。逆に、Windows向けに書いた設定をMacやLinuxに持っていくと、指定したコマンドが存在せず起動できません。

**症状としては「設定は書いたのにサーバーが出てこない」という形で出ます。** エラーの文言が出ない場合もあるので、環境をまたいで設定をコピーした覚えがあるなら、まずここを疑ってください。

対処は単純で、その環境向けの書き方に直すことです。設定ファイルを共有したい場合は、環境ごとに分けて持つほうが結局は楽になります。

原因2: 鍵を環境変数から読ませていて、その変数が未設定

外部サービスを使うには、多くの場合パスワードにあたる文字列が必要です。これを設定ファイルに直接書くと、うっかり他人に見える場所へ共有してしまう危険があるため、環境変数から読ませる書き方がよく使われます。

ここで起きるのが、**変数を登録し忘れたまま起動してしまう**ケースです。この場合、設定の読み込み自体に失敗するので、そのサーバーだけでなく設定全体が効かなくなることがあります。「昨日まで動いていたのに今日は全部おかしい」というときは、これを疑ってください。別の端末で作業を始めた、パソコンを買い替えた、といったタイミングで起きます。

確認方法は単純で、その変数が今の環境で読めるかを表示させるだけです。空だったら登録し忘れです。**なお、設定ファイルに直接書いてしまった鍵は、あとから消しても記録には残ります。** 共有する予定がある設定なら、最初から環境変数にしておくほうが安全です。

原因3: そもそも外部に届いていない

設定が正しくても、通信が遮断されていれば動きません。これがいちばん気づきにくい原因です。

会社のネットワークや、外部への通信を制限している環境では、接続先に届かないため「なぜか動かない」としか見えません。設定を何度見直しても直らないので、ここで時間を使い果たしがちです。

切り分け方は、**設定の話をいったん離れて、その接続先に届くかどうかだけを確かめる**ことです。届いていないと分かれば、設定をいじるのをやめられます。これが分かるだけでも大きな前進です。

届かないと確定した場合、選択肢は2つです。その機能を使わない前提に切り替えるか、通信が通る別の場所で実行するかです。実際、外部サービスを叩く処理だけを別の環境に任せて、結果のファイルだけを手元で読む、という分け方は現実的な解になります。

切り分けの順番

つながらないときは、次の順で確認すると早く終わります。上から順に、確認にかかる手間が小さい順です。

**1. 認識されている一覧を表示する。** 出てこないなら設定が読まれていません。置き場所（スコープ）と、環境をまたいだコピーを疑います。

**2. 環境変数が読めるか確認する。** 空なら登録し忘れです。設定全体が効かなくなることがあるので、影響範囲は大きめです。

**3. 接続先に届くか確認する。** 届かないなら、設定は正しくても動きません。ここまで来たら設定をいじるのをやめてください。

この3つで大半は特定できます。**逆に、いきなり設定ファイルを書き直すのは遠回りです。** どこで止まっているかが分からないまま直しても、直ったかどうかが判断できません。

MCPを足す前に考えたいこと

最後に、少し引いた話をします。MCPは強力ですが、設定の手間に見合うかは作業によります。

手元のファイルを扱う作業（整理、集計、書類作成）は、MCPなしで完結します。このサイトに載せているプロンプトやスキルも、ほとんどが手元のファイルだけで動きます。**まずそちらで効果を確かめてから、外部データが必要になった時点でMCPを足すほうが、挫折しにくいです。**

また、繰り返す作業であれば、外部連携より先にスキルにするほうが効くことが多いです。手順を覚えさせるだけで、毎回の手間は大きく減ります。使い分けは別のガイドにまとめました。

よくある質問

設定ファイルを書いたのにサーバーが認識されません。

まず認識されている一覧を表示させて、そこに出ているかを確認してください。出ていない場合、置き場所（効く範囲）が想定と違うか、別の環境向けに書かれた設定をそのままコピーしている可能性が高いです。起動コマンドの指定方法はWindowsとMacで変わります。

昨日まで動いていたのに、今日は設定全体がおかしくなりました。

鍵を環境変数から読ませている場合、その変数が未設定だと読み込み自体に失敗し、他のサーバーまで巻き添えになることがあります。端末を変えた、パソコンを買い替えた、といったタイミングで起きやすいので、変数が読めるか確認してください。

設定は正しいはずなのに外部サービスに接続できません。

通信が遮断されている可能性があります。会社のネットワークや、外部への通信を制限している環境では、設定が正しくても届きません。設定の話を離れて、その接続先に届くかどうかだけを先に確かめてください。届いていないと分かれば、設定をいじるのをやめられます。

MCPは最初から設定したほうがいいですか？

必須ではありません。手元のファイルを扱う作業（整理・集計・書類作成）はMCPなしで完結します。最初から全部つなごうとして設定でつまずき、肝心の作業に進めないことがよくあるので、実際に使う1つだけを必要になった時点で足すことをおすすめします。

鍵は設定ファイルに直接書いてもいいですか？

共有する予定がないなら動きはしますが、おすすめしません。設定ファイルを他人と共有したり記録に残したりすると、あとから消しても記録側には残ります。最初から環境変数にしておくほうが安全です。

関連する解説ガイド

• Claude Codeがうまく動かないときに見る8箇所：インストールは終わったのに思った通りに動かない、という状態をほどくためのチェックリストです。作業フォルダ・権限・CLAUDE.md・スキル・MCPの順に、詰まりやすい箇所と直し方をまとめました。
• Claude CodeをWindowsで使う（導入とつまずきどころ）：WindowsでClaude Codeを導入するときに迷う箇所を、ターミナルの選び方・インストール先・パスと文字コード・会社貸与PCの制約の順に整理しました。MacとWindowsのどちらで使うか迷っている場合の判断材料も載せています。
• Claude Codeのスキルとサブエージェントの違い（CLAUDE.mdとの使い分け）：CLAUDE.md・スキル・サブエージェントは似て見えますが、役割がはっきり分かれています。「いつ読まれるか」を軸に3つを整理し、どれを作るべきかの決め方と、実際の作り方をまとめました。