Claude CodeのMCP設定：.mcp.jsonとlocal・project・userの優先順位

チームから受け取った .mcp.json を更新したのに、自分だけ古いMCPへつながる。そんなときは、接続先を書き換える前に、同じサーバー名が別のスコープにないかを確かめます。AIへ仕事の続きを渡すには、会話の記録に加えて、どの設定を使う想定かも残しておくと確認しやすくなります。

この記事はClaude Code CLIの local・project・user を対象にします。2026年10月24日に公式資料を確認し、優先順位を合成データで試す説明用コードを書きました。Claude Code本体での接続、認証、設定変更は実施していません。

#MCP設定はどこに保存されるか

同名サーバーではlocal、project、userの順に優先され、上位のエントリ全体が使われます。下位のフィールドは混ざりません。保存先と優先順位の根拠は公式のMCPスコープ説明です。

この順序は三つのスコープの比較です。managed設定、plugin、claude.aiからの接続は実験の対象外です。公式資料にはDesktopのCodeタブで同名stdioサーバーを扱う例外もあり、この記事のCLI向けの順序をそのまま当てはめないでください。

#同名のnotesを三つ置く実験

実サービスを使わず、notes という名前に三つのURLを用意しました。.invalid のURLは合成した値で、コードは通信しません。projectだけに X-Demo ヘッダーを加え、選ばれなかった設定の一部が残るかも調べます。

次の二つのファイルを同じフォルダーへ保存してください。判定関数 mcp-scope.mjs と 入力と実行例 mcp-scope-demo.mjs を配布しています。Node.js 22以降またはBunで実行できます。

node mcp-scope-demo.mjs
# または
bun mcp-scope-demo.mjs

入力は実際の設定ファイルではなく、各スコープのサーバー一覧を分けたJSONです。

{
  "local": { "notes": { "type": "http", "url": "https://local.example.invalid/mcp" } },
  "project": {
    "notes": {
      "type": "http",
      "url": "https://project.example.invalid/mcp",
      "headers": { "X-Demo": "project-only" }
    }
  },
  "user": { "notes": { "type": "http", "url": "https://user.example.invalid/mcp" } }
}

実行結果では、localWins のscopeは local、serverのURLは https://local.example.invalid/mcp です。serverにheadersはありません。localの一覧を空にした projectWins はprojectを選び、X-Demo も残ります。さらにprojectを空にした userWins はuserを選びます。

absent は not-found、壊れたJSONの invalid は invalid-input になります。これは当サイトの関数が返す状態名で、Claude Codeのエラー表示ではありません。2026年10月24日にNode.js v26.12.1とBun 1.3.11で実行し、両方で同じJSONが出力されました。

#共有した設定が使われないときの確認順

まず、使うつもりのサーバー名と、共有した .mcp.json の版を確認します。その名前に個人のlocal設定があれば、projectより優先される可能性があります。実験のようにURLだけが置き換わると考えず、headersを含むエントリ全体を比較してください。

次に、接続先・必要な権限・設定の持ち主を確認します。共有ファイルに資格情報を足して解決しようとせず、秘密値を含まない設定の差分から調べるのがこの記事の提案です。承認や認証は別の確認として扱い、設定名の一致を接続成功とみなしません。

作業を次の人やAIへ渡す記録には、「対象プロジェクト」「サーバー名」「想定スコープ」「共有ファイルの版」「接続は未確認か確認済みか」を残します。会議メモの接続を調べるならCircleback MCPの設定と読み取り範囲、会話をまたぐ記録ならClaude Codeのコンテキスト引き継ぎへ進めます。

#このコードで分からないこと

関数は渡されたJSONだけを読みます。ホームの設定や環境変数を読まず、ファイルを変更せず、JSON中のコマンドも実行しません。不正なJSONやスコープの型は拒否しますが、MCP設定全体のschema検証器ではありません。空のserverオブジェクトもデータとして受け取るため、selected は利用できる設定だという判定ではありません。

この実験は公式の三スコープの規則を説明用に実装したものです。実際のCLIの全設定ソース、認証、承認、組織ポリシー、環境変数の展開は再現しません。接続先の正しさやAIが意図どおりに道具を使うかも、別に確認する必要があります。