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

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

追加は claude mcp add の1行で済みますが、書き方を間違えると「承認待ち」や「接続失敗」のまま使えません。

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

この記事は、2026年9月29日時点の公式ドキュメントと、Windows上の Claude Code v2.1.284 で実際に登録した結果にもとづいています。

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 側の指定は、必ず — より前に書きます。

APIキーなどを渡すときは –env を使います。

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

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

同じ名前のサーバーが複数のスコープにあると、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} のように環境変数を使えるので、キーを直接書かずに共有できます。

Windowsで追加するときの注意

npxは cmd /c を付けるのが確実

公式ドキュメントは、Windowsで npx を使うサーバーは cmd /c で包むよう案内しています。

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

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

つながらないときは、まず cmd /c を付けて登録し直してみてください。

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 が /c をフォルダのパスと見なして変換してしまうためです。

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

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

claude mcp add 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

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

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 を付ける（Git Bash なら //c）
4. –env などの指定が — より後ろに入っていないかを見る
5. 対話中に /mcp を開き、表示されるエラーの中身を見る

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

MCP_TIMEOUT=10000 claude

ネット上のサーバーは、つながらなくても1〜32秒の間隔で最大5回まで自動でつなぎ直します。

サーバーからの返答が長すぎるときの上限は、MAX_MCP_OUTPUT_TOKENS で変えられます（初期値は25,000トークン）。

まとめ

• ネット上は –transport http、手元は — の後ろに起動コマンド
• 自分だけなら local、チームで共有するなら –scope project
• Windowsの npx は cmd /c を付けるのが確実で、Git Bash では //c と書く
• Pending approval は、対話モードで一度許可すれば使える
• つながらないときは claude mcp get と /mcp でエラーの中身を見る

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