Claude CodeでMCPサーバーを設定する手順を解説

Claude CodeでMCPサーバーを追加する具体的な設定手順

Claude CodeでMCPサーバーを設定する最短ルートは、ターミナルでclaude mcp addを実行することです。GUIの設定画面を探す必要はなく、コマンド一発で登録され、次回起動時から使えます。

claude mcp addコマンドで標準入出力型サーバーを登録する

ローカルで動く標準入出力（stdio）型のサーバーは、実行コマンドをそのまま渡して登録します。ファイルシステム系のMCPサーバーなら次のように書きます。

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

肝は--以降が実際に起動されるコマンドである点です。区切りを省くとClaude Code側のオプションと解釈され、意図した引数が渡りません。ここは必ず入れてください。

設定スコープ（local・project・user）の使い分け

登録先はlocal・project・userの3スコープから選べます。--scopeを付けなければlocalとなり、自分の端末のそのプロジェクトだけで有効です。使い分けの目安は次の通りです。

• local：試験導入や個人用の一時的なサーバー
• project：チーム全員で共有したい設定（後述の.mcp.jsonに書き出される）
• user：全プロジェクトで使う自分専用のツール

APIキーを含むサーバーをprojectスコープに入れると、認証情報がリポジトリに載ってしまいます。その場合はuserかlocalを選んでください。

接続方式ごとの設定の違いとプロジェクト共有時の記述例

MCPサーバーには、ローカルプロセスを起動するstdio型のほかに、URL越しに接続するリモート型もあります。方式が違えばコマンドの書き方も変わるので、対象がどちらかを先に確認しておくと迷いません。

SSE・HTTP接続を使うリモートMCPサーバーの設定

リモートサーバーは--transportで方式を指定します。HTTPやSSEのエンドポイントに繋ぐ場合の例です。

claude mcp add --transport http my-server https://example.com/mcp

認証が必要なサービスでは--header "Authorization: Bearer xxx"のようにヘッダを付与します。stdio型のように--でコマンドを渡す書き方とは根本的に異なるため、リモートなのにコマンドを書いてしまう取り違えに注意してください。

.mcp.jsonでチームにMCP設定を共有する方法

projectスコープで追加した設定は、プロジェクト直下の.mcp.jsonに自動で書き出されます。これをGitで共有すれば、メンバーは各自コマンドを打たずに同じMCP環境を再現できます。

ただしAPIトークンなどの秘匿値を直書きすると事故のもとです。値は${API_KEY}のように環境変数参照にし、実体は各自の環境に持たせるのが実運用の定石です。

「MCP server failed to connect」が起きる原因と設定を検証する手順

登録したのに使えない場合、多くは接続エラーです。「MCP server failed to connect」と出たら、登録の有無よりも起動と経路の問題を疑うのが早道です。

claude mcp listと/mcpで接続状態を確認する

設定が正しく読み込まれているかはclaude mcp listで確認します。ここに出てこなければ、スコープ違いか登録先ディレクトリのずれです。さらにClaude Code起動中に/mcpを打てば、各サーバーがconnectedかfailedかをその場で確認できます。connectedになって初めて設定完了と判断してください。

環境変数・パスの解決失敗を切り分けるチェックポイント

failedの典型は、コマンドのパスが解決できないケースです。Claude Codeがnpxやnodeを見つけられず起動に失敗している状態で、GUI起動時とターミナル起動時でPATHが異なると再現します。

切り分けには、同じコマンドをターミナルに手で貼って単体起動できるか試すのが確実です。手元で動いてClaude Code経由で動かないなら環境変数の受け渡し、どちらでも動かないならコマンドや引数自体の誤りと判断できます。