MENU
Amazonで商品を見るセール会場へ
  1. ホーム
  2. Claude
  3. Claude Code│MCPサーバーの追加方法と接続エラーの直し方｜claude mcp addとスコープ

Claude Code│MCPサーバーの追加方法と接続エラーの直し方｜claude mcp addとスコープ

広告
Claude

MCPサーバーを追加すると、Claude Codeから外部のサービスや手元の道具を使えるようになります。

登録にはclaude mcp addを使います。登録成功は設定の保存を意味し、接続・認証・ツールの利用許可は別に確認します。

  • ネット上のサーバー：claude mcp add --transport http 名前 URL
  • 手元で動かすサーバー：claude mcp add 名前 -- 起動コマンド
  • チームで共有するなら --scope project（.mcp.json に保存）
  • 状態の確認：claude mcp list、対話中なら /mcp

2026年10月23日に公式資料と照合しました。Windows上のv2.1.284の出力は9月29日の記録です。今回はサーバー登録・認証・接続を実行していません。

目次

claude mcp addの書き方

ネット上のサーバー（HTTP）

claude mcp add --transport http notion https://mcp.notion.com/mcp

公式ドキュメントは、ネット上のサーバーには HTTP を勧めています。

SSE という方式もありますが、今は非推奨です。

ログインが要るサーバーは、追加したあと対話中に /mcp を開いてサーバーを選ぶと、ブラウザーでログインできます。

ターミナルから claude mcp login 名前 でもログインできます。

手元で動かすサーバー（stdio）

claude mcp add files -- npx -y @modelcontextprotocol/server-filesystem C:/demo/mcp-demo

-- より後ろが、サーバーを起動するコマンドです。

--scope や --env などの Claude Code 側の指定は、必ず -- より前に書きます。

--envは複数の値を受け取るため、直後にサーバー名を置くと値として解釈されます。例のように名前を先に書いてください。キーの直書きは履歴や保存設定に残るため、共有設定では環境変数参照を使います。

claude mcp add myserver --env API_KEY=自分のキー -- npx -y サーバーのパッケージ名
スポンサーリンク

3つのスコープと保存場所

スコープ指定保存場所使える範囲
local（初期値）指定なし か --scope localホームフォルダの .claude.json今のプロジェクトの自分だけ
project--scope projectプロジェクト直下の .mcp.json今のプロジェクトの全員（Gitで共有）
user--scope userホームフォルダの .claude.json自分の全プロジェクト
Claude Code公式ドキュメント「Connect Claude Code to tools via MCP」をもとに作成

CLIでは同じ名前のサーバーが複数のスコープにあると、local、project、userの順に定義全体が選ばれ、項目ごとには結合されません。

--scope project で追加すると、プロジェクト直下に次のような .mcp.json ができます。

{
  "mcpServers": {
    "files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx -y @modelcontextprotocol/server-filesystem C:/demo/mcp-demo"
      ],
      "env": {}
    }
  }
}

.mcp.json の中では ${API_KEY} のように環境変数を使えるので、キーを直接書かずに共有できます。

参照する変数はClaude Codeを起動する環境に設定しておきます。

未設定で既定値もない場合、通常は警告が出て${VAR}という文字列がそのまま残るため、claude mcp listの警告を確認してください。

リモート接続のurlやheadersではANTHROPIC_API_KEYなど一部の認証変数が空文字として扱われるので、Claude Code自身の認証変数を外部サーバー用のキーとして流用しないでください。

Windowsで追加するときの注意

npxが起動しないときは実行方法を確認する

本文のcmd /cはWindows向けの回避例です。現在取得した公式資料には、全環境でこれを必須とする記載は確認できませんでした。直接起動できる環境もあるため、実際のエラーを確認してください。

claude mcp add --scope project files -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:/demo/mcp-demo

今回の環境では、cmd /c を付けずに登録したものも動きました。

同じ名前・同じスコープへの再追加はエラーになります。登録例は未登録の環境向けです。既存設定を直す場合はclaude mcp getで保存先と引数を確認し、重複登録を避けてください。

Git Bashだと /c が C:/ に変わる

Git Bash から cmd /c と打って登録したところ、/c が C:/ に書き換えられて保存されました。

Added stdio MCP server files with command: cmd C:/ npx -y @modelcontextprotocol/server-filesystem C:/demo/mcp-demo to project config

この記録ではGit Bashの引数変換が原因でした。シェルの版や設定で異なるため、claude mcp getで保存された引数を確認してください。

この状態ではサーバーを起動できません。

Git Bash では //c と2本重ねて書くか、PowerShell やコマンドプロンプトから登録します。

claude mcp add --scope project files -- cmd //c "npx -y @modelcontextprotocol/server-filesystem C:/demo/mcp-demo"
Added stdio MCP server files with command: cmd /c npx -y @modelcontextprotocol/server-filesystem C:/demo/mcp-demo to project config

つながったかを確かめる

claude mcp list

登録されたサーバーの状態が表示されますが、Pending approvalなどは接続を試した結果ではなく設定上の状態です。

見つからないサーバーはclaude mcp get 名前でも確認し、拒否設定や無効化が原因でないかを調べてください。

1つのサーバーの設定を詳しく見るときは claude mcp get 名前、消すときは claude mcp remove 名前 です。

対話中なら /mcp で同じ一覧を開き、エラーの中身やログインの状態を見られます。

「Pending approval」は承認待ち

--scope project で追加した直後に claude mcp list を実行すると、次のように出ました。

files: cmd /c npx -y @modelcontextprotocol/server-filesystem C:/demo/mcp-demo - ⏸ Pending approval (run `claude` to approve)

これは故障ではありません。

.mcp.json はほかの人がGitに入れたファイルかもしれないので、対話モードで最初に使うときに許可を求める仕組みです。

claude で対話を始めて、表示される確認で許可すれば使えるようになります。

一方、claude -p で動かしたときは、確認なしで読み込まれました。

許可した内容をやり直したいときは、claude mcp reset-project-choices を実行します。

接続に失敗するときの確認順

わざと存在しないコマンドで登録したサーバーは、「Connection closed」で接続に失敗しました。

  1. claude mcp get 名前 で、保存されたコマンドやURLが意図どおりかを見る
  2. stdio のサーバーは、-- より後ろのコマンドをそのままターミナルで実行して動くかを見る
  3. Windowsでnpxの直接起動に失敗している場合は、保存済み設定を確認したうえでcmd /cを使う回避策を検討する
  4. --env などの指定が -- より後ろに入っていないかを見る
  5. 対話中に /mcp を開き、表示されるエラーの中身を見る

起動待ちはMCP_TIMEOUTで指定します。次の例はBash用です。PowerShellでは$env:MCP_TIMEOUT = "10000"を実行してからclaudeを起動します。ツール実行時間の上限とは別です。

MCP_TIMEOUT=10000 claude

リモート接続の途中切断は最大5回の再接続を試みます。HTTP/SSEの初回の一時的な失敗は最大3回など、失敗の種類・実行モードで異なります。認証エラーは再ログインなどの対応が必要です。

既定の出力上限は25,000トークンでMAX_MCP_OUTPUT_TOKENSから変更できますが、文字数やサーバー側の制限は別です。長い成功テキストはファイルに保存される場合があり、上限変更だけで全内容が会話へ入るわけではありません。

スポンサーリンク

まとめ

  • ネット上は --transport http、手元は -- の後ろに起動コマンド
  • 自分だけなら local、チームで共有するなら --scope project
  • Windowsで起動に失敗する場合は cmd /c を検討し、Git Bashでは保存された引数を確認する
  • Pending approval は、対話モードで一度許可すれば使える
  • つながらないときは claude mcp get と /mcp でエラーの中身を見る

参考：Claude Code公式ドキュメント「Connect Claude Code to tools via MCP」（2026年10月23日に再確認）。

よくある質問：Claude CodeにMCPサーバーを追加するとき

Claude CodeにMCPサーバーを追加するには、どう書きますか？

ネット上のサーバーは claude mcp add --transport http 名前 URL、手元で動かすサーバー（stdio）は claude mcp add 名前 -- 起動コマンド です。

公式ドキュメントは、ネット上のサーバーには HTTP を勧めていて、SSE という方式は今は非推奨です。

ログインが要るサーバーは、どうすればよいですか？

追加したあと、対話中に /mcp を開いてサーバーを選ぶと、ブラウザーでログインできます。

ターミナルから claude mcp login 名前 でもログインできます。

APIキーなどを渡すには？ オプションの置き場所は？

--env を使います。

--scope や --env などの Claude Code 側の指定は、必ず -- より前に書きます。

-- より後ろは、サーバーを起動するコマンドです。

スコープは、どう選びますか？

local（初期値）は今のプロジェクトの自分だけで、ホームフォルダの .claude.json に保存されます。

--scope project は今のプロジェクトの全員（Gitで共有）で、プロジェクト直下の .mcp.json に、--scope user は自分の全プロジェクトで、ホームフォルダの .claude.json に保存されます。

CLIでは同じ名前のサーバーが複数のスコープにあると、local、project、userの順に定義全体が選ばれ、項目ごとには結合されません。

.mcp.json の中では ${API_KEY} のように環境変数を使えるので、キーを直接書かずに共有できます。

Windowsで npx のサーバーを追加するときの注意は？

本文のcmd /cはWindows向けの回避例です。現在取得した公式資料には、全環境でこれを必須とする記載は確認できませんでした。直接起動できる環境もあるため、実際のエラーを確認してください。

記事の環境では、cmd /cを付けずに登録したものも動きました。

つながらないときはclaude mcp get 名前で保存済みのコマンド・引数とスコープを確認し、必要な箇所を直してください。

同じ名前を同じスコープへ再追加するとエラーになるため、原因を確認せずaddを繰り返さないでください。

記事のGit Bash環境では/cがC:/へ変換されました。すべての環境で必ず起きるとは限りません。

Git Bash では //c と2本重ねて書くか、PowerShell やコマンドプロンプトから登録します。

つながったかどうかは、どう確かめますか？

claude mcp list で、登録したすべてのサーバーと、つながっているかどうかが一覧で出ます。

1つのサーバーの設定を詳しく見るときは claude mcp get 名前、消すときは claude mcp remove 名前、対話中なら /mcp で同じ一覧を開き、エラーの中身やログインの状態を見られます。

「Pending approval」と出たら、故障ですか？

故障ではありません。

.mcp.json はほかの人がGitに入れたファイルかもしれないので、対話モードで最初に使うときに許可を求める仕組みです。

claude で対話を始めて、表示される確認で許可すれば使えるようになります。

claude -p で動かしたときは、確認なしで読み込まれました。

許可した内容をやり直したいときは、claude mcp reset-project-choices を実行します。

接続に失敗するときは、何を確認しますか？

claude mcp get 名前 で、保存されたコマンドやURLが意図どおりかを見ます。

stdio のサーバーは、-- より後ろのコマンドをそのままターミナルで実行して動くか、--env などの指定が -- より後ろに入っていないかを見ます。

対話中に /mcp を開き、表示されるエラーの中身も見ます。

Authorizationヘッダーを自分で設定したサーバーの401・403は、そのヘッダーの認証値を確認します。

この場合はOAuthへ自動的に切り替わらないため、OAuthを使う意図なら不要なAuthorizationヘッダーを外してからログインしてください。

起動に時間がかかるサーバーは、環境変数 MCP_TIMEOUT で待つ時間（ミリ秒）を延ばせます。

リモート接続の途中切断は最大5回の再接続を試みます。HTTP/SSEの初回の一時的な失敗は最大3回など、失敗の種類・実行モードで異なります。認証エラーは再ログインなどの対応が必要です。

現行仕様は2026年10月23日に照合しました。Windows/Git Bashの再現、OAuth認証、実際の再試行回数は今回検証していません。

最新は公式ページで確認してください。

AI用PCを買う前に：クラウド利用とローカル実行の違いを確認する

Claude
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

関連記事

次に学ぶ・作業環境を選ぶ

学習を続けたい方や、作業環境を整えたい方は、目的に合うガイドをご覧ください。

生成AIのおすすめ書籍

周辺機器の優先度

目次