MCPサーバーが繋がらない時のチェックリスト — claude mcp add・stdio・HTTP・環境変数

結論

「mcp 繋がらない」「claude mcp add 失敗」で詰まるケースの大半は、MCP の仕組みそのものではなく、起動の前提条件が満たされていないことが原因です。MCP はあくまで「AI クライアントが外部ツールを呼び出すための共通インターフェース」であり、実体は別プロセスのサーバーです。つまり「サーバーが起動できているか」と「クライアントがそこへ正しくつなげているか」を分けて考えるのが切り分けの基本になります。

stdio と HTTP はどう違い、設定はどう変わる?

トランスポート種別を取り違えると、何をどう設定しても繋がりません。MCP の代表的なトランスポートは2つです。

• stdio: クライアントがサーバーのプロセスを起動し、標準入出力でやり取りします。ローカルの CLI ツールやローカルファイル操作系のサーバーで主流です。設定には起動 command と引数、必要なら作業ディレクトリと環境変数を書きます。
• HTTP: すでに起動しているサーバーへネットワーク経由でつなぎます。リモートのホスト型サーバーや、別途立てたローカルサーバーで使います。設定には接続先 url を書きます。

混乱の元は、この2つで設定キーがまったく違う点です。stdio は「何を起動するか」、HTTP は「どこへつなぐか」を書きます。stdio のサーバーを HTTP のつもりで url だけ書いても、起動するプロセスがないので当然繋がりません。

claude mcp add の典型ミスは?

最頻出は「command フィールドが必須なのに埋まっていない」ことです。stdio サーバーは、登録した command(と引数)をクライアントが子プロセスとして起動して初めて通信が始まります。

スコープ(プロジェクト単位かユーザー全体か)を間違えて、別ディレクトリでは登録が見えていない、というのもよくあります。登録時に指定したスコープと、いま /mcp を叩いている場所が一致しているか確認してください。

stdio サーバーの最小構成は、概念的には次のような形になります(具体的なキー名やコマンド書式はお使いのクライアントのバージョンで変わるため、最新は公式ドキュメントで確認してください)。

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@scope/my-mcp-server"],
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

ここで command が空、もしくは存在しない実行ファイルを指していると、サーバーは起動しません。npx や node を使う場合は、それらに PATH が通っているかも要確認です。

接続状態はどう確認する?

まず Claude Code 内の /mcp で、登録済みサーバーの一覧と接続状態を見ます。ここが failed や disconnected なら、設定は読まれているがサーバーが立ち上がらない、もしくはハンドシェイクに失敗しています。

/mcp に名前すら出てこない場合は、そもそも設定が読まれていません。設定ファイルのパス・スコープ・JSON の文法エラー(末尾カンマや引用符)を疑ってください。

最短の確認は、登録した起動コマンドをそのままターミナルで実行することです。

# 設定に書いたのと同じコマンドを手で起動してみる
npx -y @scope/my-mcp-server

これでエラーが出れば、それが不通の真因です(モジュール未インストール、Node のバージョン不整合、APIキー未設定など)。手で起動できるのにクライアントから繋がらないなら、問題は設定の渡し方(パス・作業ディレクトリ・環境変数)側にあります。

環境変数や秘密はどう渡す?

設定ファイルの env に渡すか、サーバー起動時に読まれる OS 環境から渡します。よくあるのは「ターミナルでは環境変数が見えているのに、クライアントが起動するプロセスには渡っていない」というズレです。

クライアントは、あなたのシェルの .bashrc や .zshrc を必ずしも読み込まずにサーバーを起動します。したがって、シェルでだけ export した変数は届かないことがあります。確実なのは、設定の env に明示する方法です。

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./server.js"],
      "env": {
        "API_TOKEN": "...",
        "LOG_LEVEL": "info"
      }
    }
  }
}

ただし API キーなどの秘密を設定ファイルに直書きしてリポジトリへコミットするのは避けてください。OS の環境変数や専用のシークレット管理から読み込む形にし、設定ファイルには値そのものを残さないのが安全です。

Windows 固有の落とし穴は?

Windows では、パス区切り・PATH 解決・改行コードの3点で詰まりやすいです。

• パス区切り: JSON 内のバックスラッシュはエスケープが要ります。C:\\path\\to\\server のように二重にするか、フォワードスラッシュ C:/path/to/server を使うと安定します。
• PATH 解決: npx や node がクライアントの起動環境で見つからないことがあります。コマンドをフルパスで指定する、もしくはランチャーに PATH が通る形で起動するのが確実です。
• 改行コード: 設定ファイルや起動スクリプトに CRLF が混じると、引数や値の末尾に余計な文字が入ることがあります。コマンドが「見た目は合っているのに動かない」ときは改行を疑ってください。

この順で潰していけば、「サーバーが起動していない」のか「起動はするが通信できていない」のか「そもそも設定が読まれていない」のかが必ず分かれます。原因が特定できれば、対処はそのカテゴリに対してだけ行えば済みます。

よくある質問

claude mcp add したのに繋がりません。最初に何を疑うべきですか?

コマンドが絶対パスで起動できるか、作業ディレクトリ、環境変数、トランスポート種別の4点をまず疑います。多くの不通はこのいずれかの取り違えです。設定の command フィールドが空で URL だけになっていないかも確認します。

stdio と HTTP はどう使い分けますか?

ローカルでプロセスを起動して標準入出力でつなぐなら stdio、すでに立っているサーバーへネットワーク経由でつなぐなら HTTP です。stdio は command と引数、HTTP は url を設定します。両者で設定キーが異なる点が混乱の原因になりがちです。

接続状態はどこで確認できますか?

Claude Code 内では /mcp コマンドでサーバー一覧と接続状態を確認できます。failed や disconnected と出る場合は、起動コマンドをターミナルで単体実行してエラーを直接読むのが近道です。

環境変数や APIキーはどう渡しますか?

設定ファイルの env 欄にキーと値を書くか、サーバー起動時に読まれる環境から渡します。秘密情報を設定ファイルに直書きせず、OS の環境変数や専用のシークレット管理から参照するのが安全です。

Windows で特に詰まりやすい点は何ですか?

パス区切りのバックスラッシュ、npx や node への PATH 解決、改行コードの混入です。コマンドはフルパス指定にし、引数のクォートと改行に注意すると安定します。

関連記事

• egov-law-mcpが動かない時の対処法
• MCPとは何か。e-Gov法令MCPを例に、作る前に決める設計境界
• Hooks で MCP エージェントを安全に運用する
• Claude Code セットアップガイド