Claude Code の MCP 設定:local・project・user の違いと .mcp.json

公開: 2026年10月15日 ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

MCP のスコープは3つ:読み込まれる範囲と共有の有無

この記事は、Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)に MCP サーバー(外部のツールやサービスをつなぐ仕組み)を設定するときのスコープを整理します。執筆時点(2026年10月)の公式ドキュメントに基づきます。

公式ドキュメントによると、スコープは、サーバーがどのプロジェクトで読み込まれるか、設定をチームと共有するかどうかを決めます。

• local:現在のプロジェクトのみで読み込まれ、チームとは共有されません。保存先は ~/.claude.json です。
• project:現在のプロジェクトのみで読み込まれ、バージョン管理を通じてチームと共有されます。保存先はプロジェクトルートの .mcp.json です。
• user:自分のすべてのプロジェクトで読み込まれ、チームとは共有されません。保存先は ~/.claude.json です。

管理者が managed configuration(管理者による一括設定)で、全利用者向けにサーバーを配備・提供することもできます。詳細は公式ドキュメントで確認してください。

出典: Connect Claude Code to tools via MCP

local スコープ(既定):自分だけ・そのプロジェクトだけ

公式ドキュメントでは、local が既定のスコープです。local のサーバーは追加したプロジェクトでだけ読み込まれ、自分専用のままです。~/.claude.json の中の、そのプロジェクトのパスの下に保存されるので、ほかのプロジェクトには同じサーバーは現れません。個人の開発用サーバー、実験的な設定、認証情報をバージョン管理に入れたくないサーバーに向くとされています。

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

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

このコマンドは、~/.claude.json の中の現在のプロジェクトの項目に書き込みます。/path/to/your/project で実行した結果は次のとおりです。

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

注意点として、MCP の「local スコープ」は一般的なローカル設定とは別物です。MCP の local は ~/.claude.json(ホームディレクトリ)に保存され、一般的なローカル設定は .claude/settings.local.json(プロジェクトディレクトリ)を使います。

出典: Connect Claude Code to tools via MCP

project スコープと .mcp.json:チームで同じ設定を使う

project スコープは、プロジェクトのルートにある .mcp.json に設定を保存します。追加すると Claude Code がこのファイルを自動で作成または更新します。.mcp.json をバージョン管理に入れれば、チーム全員が同じ MCP ツールとサービスを使えます。

# Add a project-scoped server
claude mcp add --transport http shared-server --scope project https://example.com/mcp

できあがる .mcp.json は次の形式です。

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

承認の確認が出る場合と出ない場合

セキュリティ上、対話セッションでは、.mcp.json の project スコープのサーバーを使う前に承認を求められます。承認の選択をやり直すには claude mcp reset-project-choices を実行します。

一方、claude -p の実行、Agent SDK のセッション、クラウドセッションでは確認画面を出せないため、確認なしで読み込みます。bypassPermissions モードで開始し、skipDangerousModePermissionPrompt をユーザー設定または管理設定に入れたセッションでも、確認は省かれます。それでも読み込ませたくないサーバーがある場合、公式ドキュメントは次の方法を挙げています。

• disabledMcpjsonServers に追加する(すべての権限モードで遮断されます)
• --setting-sources または SDK の settingSources で、プロジェクト設定を丸ごと除外する
• --strict-mcp-config でセッションを始める(--mcp-config で渡したサーバーだけを使います)

出典: Connect Claude Code to tools via MCP

user スコープと、同名サーバーの優先順位

user スコープのサーバーは ~/.claude.json に保存され、そのマシンのすべてのプロジェクトで使えます。自分のユーザーアカウントの専用で、他人には共有されません。個人用のユーティリティや、いろいろなプロジェクトで頻繁に使うサービスに向くとされています。

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

同じサーバーが複数の場所で定義されている場合、Claude Code は一度だけ接続し、最も優先度の高い定義を使います。その定義の項目全体が使われ、スコープをまたいでフィールドが混ぜ合わされることはありません。優先順位は次のとおりです。

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

3つのスコープ間の重複は名前で判定します。プラグインとコネクタは接続先で判定します。組織が managedMcpServers の管理設定で提供するサーバーは、これらすべてより上位です(Claude Code v2.1.259 以降が必要)。

同じ名前を異なる接続先で複数のスコープに定義すると、claude mcp list と /mcp で警告が出ます。不要な定義は claude mcp remove <name> --scope <scope> で削除できます。

出典: Connect Claude Code to tools via MCP

.mcp.json の環境変数展開と、空として読まれる変数

公式ドキュメントによると、.mcp.json では環境変数を展開できます。設定をチームで共有しつつ、マシンごとに違うパスや API キーのような機密値を各自に持たせられます。

• ${VAR}:環境変数 VAR の値に展開されます。
• ${VAR:-default}:VAR が設定されていればその値、なければ default を使います。

展開できる場所は command、args、env、url、headers です。例は次のとおりです。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

参照した変数が未設定で既定値もない場合、設定は読み込まれます。ただし claude mcp list に警告が出て、${VAR} の文字列がそのまま使われます。

注意点として、リモートサーバーの url と headers では、ANTHROPIC_API_KEY や ANTHROPIC_AUTH_TOKEN など Claude Code やクラウドの認証情報にあたる変数は、展開されず空として読まれます。変数を設定していても同じで、:-default も無視されます。API_KEY のように対象外の名前は、書いたとおり展開されます。対象の認証情報を渡したいときは、自分で付けた名前の変数にコピーして、その名前を参照します。

出典: Connect Claude Code to tools via MCP

参考(執筆時点)

• Connect Claude Code to tools via MCP(公式ドキュメント)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。