claude mcp add の --scope local / project / user の違いと使い分け

claude mcp add で MCP サーバーを追加するとき、--scope に何を指定すべきか迷います。名前から「local はローカル、user はユーザー」と推測はできますが、local と user はどちらも同じファイルに保存されるため、違いが分かりにくい部分です。

見るべき点は 保存先・共有範囲・優先順位 の 3 つです。結論として、自分だけがそのプロジェクトで使うなら local(既定)、チームで共有するなら project、自分がすべてのプロジェクトで使うなら user です。

3 つのスコープの比較

スコープ	範囲	保存先	チームと共有
local(既定)	そのプロジェクトで自分だけ	~/.claude.json のそのプロジェクトのパスの下	されない
project	プロジェクトの全員	プロジェクト直下の .mcp.json	される(バージョン管理経由)
user	自分のすべてのプロジェクト	~/.claude.json	されない

local と user はどちらも ~/.claude.json に入ります。違いは書かれる場所で、公式ドキュメントは local について「Claude Code は ~/.claude.json のそのプロジェクトのパスの下に保存するので、同じサーバーは他のプロジェクトには現れない」と説明しています。

--scope を省略すると local です。次の 2 つは同じ意味になります。

claude mcp add --transport http stripe https://mcp.stripe.com
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

使い分けの目安

状況	スコープ
認証情報を含むサーバーをバージョン管理に入れたくない	local
実験的な設定を試す	local
チーム全員に同じサーバーを使わせたい	project
自分がどのプロジェクトでも使うサーバー(検索、メモなど)	user

公式ドキュメントも local の用途を「個人用の開発サーバー、実験的な設定、バージョン管理に入れたくない認証情報を持つサーバー」と案内しています。

# チームで共有する(.mcp.json に書かれる)
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# 全プロジェクトで使う
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

project スコープと .mcp.json

--scope project で追加すると、プロジェクト直下の .mcp.json が作成・更新されます。

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

このファイルはバージョン管理に入れてチームで共有します。環境変数の渡し方は .mcp.json で環境変数を安全に渡す にまとめています。

承認プロンプトが出ない条件も明記されています。

• claude -p の実行、Agent SDK のセッション、クラウドセッションでは、プロンプトを表示できないため承認なしで読み込まれる
• bypassPermissions モードで開始し、ユーザー設定か管理者設定に skipDangerousModePermissionPrompt が設定されている場合もスキップされる

それでも特定のサーバーを読み込ませたくない場合の手段は 3 つです。

方法	効果
disabledMcpjsonServers に追加	すべての権限モードでブロックする
--setting-sources(SDK は settingSources)でプロジェクト設定を除外	プロジェクト設定ごと読み込まない
--strict-mcp-config で起動	--mcp-config で渡したサーバーだけを使う

同じ名前が複数のスコープにあるとき

同じサーバー名が複数の場所で定義されている場合、Claude Code は優先順位が最も高いソースの定義だけを使って 1 回接続します。フィールドがスコープをまたいで統合されることはありません。

1. local スコープ
2. project スコープ
3. user スコープ
4. プラグインが提供するサーバー
5. claude.ai のコネクタ

3 つのスコープは名前で重複を判定します。同じ名前を別のエンドポイントで複数のスコープに定義すると、claude mcp list の出力と /mcp で競合の警告が出ます。

確認と削除

追加したサーバーの一覧と詳細は次のコマンドで確認します。

claude mcp list
claude mcp get <name>

削除するときはスコープを指定します。

claude mcp remove <name> --scope <scope>

MCP サーバーの追加方法全体は親記事の MCP サーバーのセットアップ を参照してください。

まとめ

• --scope の既定は local。そのプロジェクトで自分だけが使う設定になる
• local と user はどちらも ~/.claude.json だが、local はプロジェクトのパスの下に保存される
• project はプロジェクト直下の .mcp.json に書かれ、バージョン管理でチームに共有される
• project のサーバーは対話セッションで承認が必要。やり直しは claude mcp reset-project-choices
• 同じ名前が複数あると local → project → user → プラグイン → コネクタの順で 1 つだけ使われる