Codexの拡張機能として人気のMCP（Model Context Protocol）。外部ツールやデータソースとつなげる強力な仕組みですが、「設定したのに接続できない」「ツールが一覧に出てこない」「タイムアウトばかり」というトラブルの声も多い分野です。
MCPのエラーは一見わかりにくいのですが、原因は設定ファイルの記述ミス・実行環境・サーバー側の問題の3つにほぼ集約されます。この記事では、症状別のチェックリスト形式で順に潰していきます。
この記事でわかること
- ✅ MCP接続エラーの3大原因と見分け方
- ✅ 症状別チェックリスト（接続できない／ツールが出ない／タイムアウト）
- ✅ 設定ファイルの確認ポイント
- ✅ 動作確認とデバッグの手順
⚠️ 本記事は OpenAI 公式とは無関係の解説記事です。
前提：MCPの仕組みをざっくり確認
MCPは「Codex本体」と「MCPサーバー（機能を提供する小さなプログラム）」が通信する仕組みです。つまりトラブルの原因は：
- 設定ファイル：Codexに「どのサーバーをどう起動するか」を伝える記述が間違っている
- 実行環境：サーバーを動かすためのNode.js等が見つからない・古い
- サーバー側：MCPサーバー自体が起動に失敗している・認証切れ
のどれかに落ちます。MCPの基本や導入手順から確認したい方は、先に MCP入門ガイド をどうぞ。
症状①：「接続できない」「connection failed」と出る
チェック1：設定ファイルの場所と文法
MCPの設定は設定ファイル（config.toml など、環境により場所が異なります）に記述します。よくあるミスは：
- カンマ・括弧の欠落などの文法エラー（1文字のミスで全体が読めなくなります）
- サーバー名の重複
- ファイルを編集したのに保存していない／別の場所の設定ファイルを編集していた
文法チェックは、設定ファイルの中身をCodex自身やWeb版に貼って「この設定ファイルに文法エラーはある？」と聞くのが手っ取り早いです。設定ファイル全般の話は 設定ガイド にまとめています。
チェック2：コマンドが実行できるか単体で試す
設定に書いた起動コマンド（例：npx -y @example/mcp-server）を、ターミナルで直接実行してみてください。
- そこでエラーが出る → Codex以前に、サーバー自体が起動できていません。エラー文を読んで解決（パッケージ名のタイプミス・ネットワークが典型）
- 直接なら動く → Codex側の設定記述か、PATHの問題（次項）
チェック3：PATHの問題（GUIアプリ特有）
ターミナルからは動くのにデスクトップアプリからは動かない場合、アプリがnpxやnodeを見つけられていないことがあります。ターミナルとGUIアプリではPATHの読み込みが異なるためです。設定のコマンドをフルパス（which npx で出るパス）で書くと解決することが多いです。
症状②：接続はできるが「ツールが出てこない」
- Codexを再起動したか：設定変更後は再起動が基本です。読み込み直しで解決するケースが最多
- サーバーの起動に時間がかかっていないか：初回は依存パッケージのダウンロードで時間がかかることがあります。少し待ってから確認
- そのサーバーが本当にツールを提供しているか：MCPサーバーには「ツール提供型」以外の種類もあります。READMEで提供機能を確認
- バージョンの相性：サーバー側パッケージが古い場合は最新版を指定して再試行
症状③：「タイムアウト」が頻発する
- ネットワーク：プロキシ・VPN・ファイアウォールがサーバーの通信を妨げていないか。切り分けは ネットワークエラーの対処 を参照
- 認証切れ：外部サービス連携型のMCPサーバー（クラウドサービスに接続するもの等）は、トークンの期限切れでタイムアウトに見えることがあります。再認証を
- サーバーの応答が遅いだけ：重い処理を提供するサーバーは応答に時間がかかります。タイムアウト設定を延ばせる場合は延長を
デバッグの基本手順（迷ったらこの順）
- 最小構成にする：MCPサーバーを1つだけ有効にして動くか確認。動けば、増やしながら犯人を特定
- 公式サンプルで試す：よく使われている定番サーバー（ファイルシステム系など）で動作確認。定番が動けば環境はOK、動かなければ環境の問題
- エラーログを読む：起動ログにエラーが出ていないか確認。エラー文をそのままCodexに貼って聞くのが最速です（エラー10選 の手法と同じ）
- クリーン再起動：Codex完全終了→再起動。それでもダメならPC再起動
セキュリティの注意（重要）
MCPサーバーは外部のプログラムを自分のPCで動かす仕組みです。導入時は次を守ってください。
- 信頼できる提供元のサーバーだけを使う（GitHubのスター数や更新履歴を確認）
- APIキーやトークンを設定ファイルに直書きしたら、そのファイルを共有・公開しない
- 用途のわからない権限を求めるサーバーは避ける
よくある質問（FAQ）
Q. 設定ファイルはどこにありますか？
A. 環境（CLI/アプリ）やバージョンによって場所が異なります。設定ガイド の確認方法を参照するか、Codexに「MCPの設定ファイルの場所を教えて」と聞いてみてください。
Q. エラーメッセージが英語で読めません
A. そのままコピーしてCodexやWeb版に貼り、「日本語で意味と対処を教えて」と聞けばOKです。エラー対応の基本は エラー10選 にまとめています。
Q. MCPサーバーを入れすぎると重くなりますか？
A. サーバーごとにプロセスが起動するので、多すぎればメモリを消費します。使っていないものは無効化を。重さが気になるときは 軽量化ガイド も参考に。
Q. 会社のPCで接続できません
A. 社内プロキシやセキュリティソフトが通信やプロセス起動をブロックしている可能性があります。情報システム部門への確認をおすすめします。
Q. どうしても動きません。MCPなしでも困りませんか？
A. Codexの基本機能（コード生成・編集・実行）はMCPなしで完結します。焦らず、まず基本機能で作業を進めながら解決するのがおすすめです（プラグイン など別の拡張手段もあります）。
まとめ
MCPの接続トラブルは、①設定ファイルの記述 → ②コマンド単体実行 → ③PATH/ネットワークの順で確認すれば大半が解決します。デバッグの鉄則は「最小構成で切り分け、エラー文はCodexに貼って聞く」。
