MCP（Model Context Protocol）は、AIアプリに外部ツールやデータをつなぐための共通仕様です。MCPサーバーを設定してもツールが出ないとき、原因の多くは「設定ファイル」「起動コマンドと実行環境」「認証情報」のどれかにあります。この記事では、確認の手間が少なく、原因として多いものから順に並べています。設定ファイルの場所やコマンドは執筆時点（2026年10月）の情報です。アプリの更新で変わることがあるため、各クライアントの公式ドキュメントとあわせて確認してください。

症状ごとに確認を始める段階

症状によって、最初に見る段階が変わります。下の表で始める位置を決めてください。迷ったときは1から順に進めます。

症状最初に見る段階
サーバー名すら一覧に出ない1（設定ファイル）→ 2（再起動）
サーバー名は出るが、赤表示や「failed」になる3（PATH）→ 4（単体起動）→ 6（ログ）
接続は成功するが、ツールを実行すると認証エラーになる5（環境変数・APIキー）
URLで接続するリモートサーバーがつながらない7（stdioとHTTPの違い）

1. 設定ファイルの場所とJSONの書き方を確認する

まず、アプリが実際に読む場所にファイルがあるかを確認します。執筆時点での主な場所は次のとおりです。

  • Claude Desktop（macOS）：~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop（Windows）：%APPDATA%\Claude\claude_desktop_config.json
  • Cursor：全プロジェクト共通は ~/.cursor/mcp.json、プロジェクト単位は .cursor/mcp.json
  • Claude Code：プロジェクト共有用はルートの .mcp.json。個人用（local・userスコープ）は ~/.claude.json

Claude Desktopでは、設定画面の「開発者」から「構成を編集」を選ぶと正しいファイルが開きます。手で作ったファイルが別の場所にある失敗を防げます。Claude Codeでは、ファイルを直接編集するより claude mcp add で登録するほうが確実です。

基本の書き方は次のとおりです。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

よくある誤りは4つあります。1つ目は最後の要素の後ろに残ったカンマです。2つ目は mcpServers の綴りや大文字小文字の違いです。3つ目は args を配列にせず、1つの文字列にまとめてしまうことです。4つ目は、WindowsのパスでJSON内のバックスラッシュを \\ と二重にしていないことです。JSONとして正しいかどうかは python3 -m json.tool ファイル名 や jq . ファイル名 で確かめられます。エラーが出なければ構文は正しいので、次の段階へ進みます。

2. アプリを完全に終了して起動し直す

Claude Desktopは、起動時に設定ファイルを読み込みます。ウィンドウを閉じただけではアプリが常駐したままなので、設定は反映されません。macOSでは Cmd+Q で終了します。Windowsではタスクトレイのアイコンから終了を選びます。Cursorでは、設定画面のMCP欄で該当サーバーをオフにしてからオンに戻すか、ウィンドウを再読み込みします。Claude Codeでは新しいセッションを始め、/mcp で接続状態を確認します。

再起動後にサーバー名が出ない場合は、段階1に戻ってファイルの場所を疑います。名前は出るが失敗表示になる場合は、段階3へ進みます。

3. コマンドのパスと、npx・uvx・nodeがPATHから見えるかを確認する

PATHは、コマンド名から実行ファイルを探すときに参照するディレクトリの一覧です。ターミナルで npx が動いても、GUIアプリからは見えないことがあります。macOSのGUIアプリは、シェルの設定ファイル（.zshrc など）で追加したPATHを引き継がないためです。nvmやVolta、Homebrewで入れたNode.jsで特に起きやすい問題です。ログに spawn npx ENOENT と出ていれば、この原因です。

対処として、which npx（Windowsは where npx）で絶対パスを調べ、command にそのパスを書きます。ただし npx は内部で node を呼びます。そのため env に PATH を指定し、nodeのあるディレクトリを含める必要がある場合もあります。Pythonで書かれたサーバーで使う uvx も同様です。uvのインストーラーを使った場合、多くは ~/.local/bin に入っています。WindowsのClaude Codeで npx を直接起動できない場合は、cmd /c npx ... の形で登録する方法が公式ドキュメントで案内されています。

4. サーバーを単体で起動してエラーを見る

設定に書いた command と args を、そのままターミナルで実行します。stdio型のサーバーは入力を待つので、何も表示されずに止まって見えます。これは正常です。すぐにエラーで終了する場合は、パッケージ名の誤りや依存パッケージの不足、Node.jsやPythonのバージョン不一致を疑います。

npx に -y を付け忘れると、初回のインストール確認でサーバーが止まります。アプリから起動したときは、この確認に誰も答えられず、タイムアウトになります。

単体で起動できたら、公式の検証ツールであるMCP Inspectorで確かめます。npx @modelcontextprotocol/inspector npx -y パッケージ名 のように実行すると、ブラウザ上でツール一覧を確認できます。Inspectorでツールが見えるのにアプリでは出ない場合、問題はサーバーではなくアプリ側の設定や環境にあります。この場合は段階5と6へ進みます。

5. 環境変数とAPIキーの渡し方を確認する

ターミナルで export した環境変数は、GUIアプリから起動したサーバーには渡りません。APIキーは、設定ファイルの env に書いて渡します。

"github": {
  "command": "npx",
  "args": ["-y", "パッケージ名"],
  "env": { "GITHUB_TOKEN": "ここにトークン" }
}

Claude Codeでは claude mcp add 名前 -e KEY=値 -- npx -y パッケージ名 の形で渡せます。.mcp.json の中では ${VAR} の形で環境変数を展開できます。接続は成功するのにツールの実行で401や403が返る場合は、変数名の違い、キーの前後の空白、権限（スコープ）の不足を確認します。キーを書いた設定ファイルをGitにコミットしないよう注意してください。

6. ログの場所と読み方

ここまでで原因がわからなければ、ログを読みます。Claude Desktopのログは、macOSでは ~/Library/Logs/Claude/、Windowsでは %APPDATA%\Claude\logs\ にあります。mcp.log には接続全体の記録が、mcp-server-サーバー名.log には各サーバーのエラー出力が残ります。macOSでは tail -n 50 -F ~/Library/Logs/Claude/mcp*.log を実行しながらアプリを再起動すると、失敗の瞬間を追えます。Cursorでは出力（Output）パネルでMCP用のチャンネルを選びます。Claude Codeでは claude --debug で起動すると、詳しい情報が出力されます。

ログの典型的なパターンと戻る先は次のとおりです。ENOENT はコマンドが見つからない状態なので段階3へ戻ります。Cannot find module や ModuleNotFoundError は依存パッケージの問題なので段階4へ戻ります。JSONの解析エラー（Unexpected token など）は、サーバーが標準出力にログを書いていることが原因です。stdio接続では標準出力をプロトコル通信専用に使うため、自作サーバーではログを標準エラー出力に書くよう修正します。タイムアウトは、初回のパッケージダウンロードに時間がかかっている場合に起きます。事前に一度単体で実行しておくと解消することがあります。

7. stdio接続とHTTP接続の違い

stdio接続では、アプリがサーバーをローカルのプロセスとして起動し、標準入出力で通信します。段階3〜5が当てはまるのはこの方式です。HTTP接続（Streamable HTTP。旧方式はSSE）では、すでに動いているサーバーへURLで接続します。PATHは関係なく、URLの誤り、サーバーの稼働状況、認証（OAuthやヘッダー）、社内プロキシやファイアウォールを確認します。

HTTP接続の設定方法はクライアントごとに異なります。Claude Codeでは claude mcp add --transport http 名前 URL で登録します。サーバーがSSEにしか対応していない場合は --transport sse を指定します。Cursorでは mcp.json に command の代わりに url を書きます。Claude Desktopでは、執筆時点ではリモートサーバーを設定ファイルではなく、設定画面の「コネクタ」からカスタムコネクタとして追加します。HTTP接続のサーバーをstdioの書き方で設定していないか、逆になっていないかを確認してください。

ここまでで直らないときの次の手

次に、環境の問題かサーバーの問題かを切り分けます。設定ファイルを、公式のファイルシステムサーバーだけを書いた最小構成に一時的に置き換えて試します。最小構成も動かなければ、PATHやアプリの設定など環境側の問題です。最小構成が動くなら、対象のサーバー側の問題です。別のクライアント（たとえばClaude DesktopとClaude Code）で同じサーバーを試すのも有効です。それでも解決しなければ、サーバーのリポジトリのIssueを検索します。報告するときは、OS、クライアントのバージョン、設定（キーは伏せる）、ログの該当部分を添えます。仕様の詳細はMCP公式サイトで確認できます。