.mcp.jsonとは？置き場所と書き方、Gitに入れる前の注意｜社内リポジトリが0件の理由【2026年】

.mcp.jsonについて僕が出した答えは、「チームで共有するためのMCP設定だから、Gitに入ってよい中身だけを書く」でした。トークンやAPIキーは直書きせず環境変数で渡し、自分だけが使う接続は user スコープ（~/.claude.json）に置きます。僕の会社は project スコープ自体を使いません。

2026年10月19日に数え直すと、GitHubに自動で同期している社内ノートのリポジトリに .mcp.json は0件でした。一方、Claude Code のプラグインのフォルダには45件あり、書き方も2通りでした。

この記事では、.mcp.json の置き場所と書き方、Git に入れる前の確認、プラグインが持ち込む .mcp.json の見方を実測と一緒に書きます。「結局コミットしていいの？」と迷う方が、自分で決められるようにしました。

.mcp.jsonの置き場所はプロジェクトのルート：チーム共有用のMCP設定ファイル

.mcp.json は、プロジェクトのルートに置く、project スコープのMCPサーバーの設定ファイルです。公式ドキュメントは、これをバージョン管理に入れてチーム全員が同じMCPを使えるようにする、という使い方を示しています。

ここでいう MCP とは、AIを業務ツールやデータにつなぐための共通規格です。仕組みや接続先の選び方は、MCPとは？MCPサーバーの仕組みと接続先で詳しく書きました。

Claude Code では、MCPサーバーを追加するときに「どの範囲で使うか」を3つのスコープから選びます。.mcp.json に入るのは、そのうち project スコープだけです。

表で見ると、共有されるのは project だけで、local と user は自分のパソコンの設定ファイルに入ります。僕なら、迷ったときは「この設定を他の人のパソコンでも動かしたいか」で決めます。

同じ名前のサーバーが何か所かにあると、公式の優先順位で1か所だけが選ばれます。順番は local、project、user、プラグイン、claude.ai のコネクタで、項目ごとには混ぜません。

なお local スコープは .claude/settings.local.json とは別物です。local のMCPの設定は、~/.claude.json の中のそのプロジェクトのパスの下に入ります。

.mcp.jsonの書き方：mcpServersの下にサーバー名を並べる

手堅いのは、claude mcp add に --scope project を付けて追加する方法です。公式ドキュメントでは、Claude Code が .mcp.json を自動で作るか書き足します。

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

できあがるファイルは、トップに mcpServers があり、その下にサーバー名ごとの設定が並ぶ形です。ネット上のサーバー（HTTP）なら、type と url を書きます。

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

手元のパソコンで動かすサーバー（stdio）は、command と args、必要なら env を書きます。下の例のサーバー名とコマンドは架空のものです。

{
  "mcpServers": {
    "local-tool": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"],
      "env": { "TOOL_TOKEN": "${TOOL_TOKEN}" }
    }
  }
}

トークンは ${VAR} で渡す

.mcp.json の中では、環境変数を展開できます。${VAR} は変数の値に、${VAR:-default} は変数があればその値、無ければ default に置き換わります。

展開できる場所は、command・args・env・url（HTTPのサーバー）・headers の5つです。認証のヘッダーも、公式の例では次のように変数で書いています。

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

変数が無く既定値も無いときは、設定は読み込まれ、claude mcp list に変数名つきの警告が出ます。サーバーは ${VAR} の文字のまま起動するので、変数を設定するか :-default を足して直します。

公式に明記された落とし穴もあります。リモートのサーバーの url と headers では、ANTHROPIC_API_KEY など、Claude Code 自身の認証情報として公式が決めた一部の変数が空として読まれ、警告も出ません。

これは、プロジェクトの .mcp.json が自分の Claude Code の認証情報を外のサーバーへ渡せないようにする仕組みです。

.mcp.jsonはGitに入れていい？秘密を書かなければ共有用のファイル

入れてよい、が公式の前提です。.mcp.json はチームで同じMCPを使うためのファイルで、バージョン管理に入れる使い方が示されています。ただし入れるのは、全員に見られても困らない中身だけです。

判断の目安を、置き場所ごとに並べます。何を書くかで、置く場所を決めるための表です。

僕なら、キーが要るサーバーを .mcp.json に書くときは、値を書いた版を一度も作らないようにします。直書きしてから変数に直しても、Git の履歴には前の版が残るからです。

使う前に承認が出る・非対話では出ない

公式ドキュメントによると、対話の画面では、.mcp.json のサーバーを使う前に承認の確認が出ます。選んだ内容をやり直したいときは、claude mcp reset-project-choices で消せます。

一方、claude -p や Agent SDK のような非対話の実行は確認を出せず、プロジェクトのサーバーを確認なしで読み込みます。

止めたいサーバーは、設定の disabledMcpjsonServers に入れます。そうすれば、どの権限モードでも読み込まれません。

承認を設定で済ませる方法もあります。enableAllProjectMcpServers は .mcp.json の全サーバーを確認なしで承認します。enabledMcpjsonServers なら、指定したサーバーだけを承認できます。

ただし、リポジトリの .claude/settings.json に書いた承認は、信頼していないフォルダでは無視されます。他人のリポジトリを開いたとき、勝手にサーバーが動かないための仕組みです。

PCを買い替えるときは、.mcp.json は Git から取り直せば付いてきます。一方で user と local の設定は自分で移す必要があり、その手順はClaude Codeを新しいMacに移行する方法にまとめました。

僕の会社が .mcp.json を作らない理由：社内ノートがGitHubに同期している

僕の会社の社内ノートは GitHub に自動で同期していて、.mcp.json ができると設定が外へ上がります。だから2026年9月15日に、MCPは原則 user スコープで追加し、project は使わないと決めました。

認証情報を含む接続でこのルールをどう当てはめたかは、MCPとは（追加するときの注意点と失敗例）の表に書いています。同じ日に足した3本の接続もすべて -s user で、トークンを設定ファイルに書く方式の接続も社内ノートの外にあります。

チームで同じMCPを使う会社なら、project スコープは便利な選択肢です。僕の会社は、共有したい相手より、外へ出したくない理由のほうが大きかった、というだけの違いです。

user スコープでつないだ接続のうち、使うたびに有料のクレジットが減るラッコキーワードだけは、消費を台帳で管理しています。減り方の実測はラッコキーワードMCPのクレジット消費に書きました。

2026年10月19日の実測：社内リポジトリは0件、プラグインの中は45件

決めたルールが守られているかを、2026年10月19日の朝に数えました。社内ノートのリポジトリと、Claude Code のプラグインが入るフォルダ（~/.claude/plugins）を、Python のスクリプトで走査しています。

走査では、node_modules と .git のフォルダを数えないようにしました。中身の値は記録せず、サーバー名と設定のキーだけを控えています。

自分で作った .mcp.json は0件でも、プラグイン経由では45件が手元にありました。プラグインのフォルダはリポジトリの外なので、こちらは Git には入りません。

.gitignore では防いでいなかった

同じ日に、社内ノートの .gitignore も確かめました。.mcp.json の行はありません。MCPを含む行は、ブラウザ操作の作業フォルダと、別の記録ファイルの除外だけでした。

つまり流出を防いでいるのは、仕組みではなく「project スコープで追加しない」という運用のほうでした。0件は、9月15日のルールが守られてきた結果で、Git が止めてくれていたわけではありません。

.gitignore に足せばいい、と考えたくなりますが、僕はそれを答えにしていません。共有しないなら、そもそも project スコープを選ぶ理由がないからです。

共有したいなら除外せず、秘密を書かない。共有しないなら user か local に置く。僕はこの2つに分けるほうが筋がよいと考えています。

プラグインの.mcp.jsonは書き方が2通りあった

公式ドキュメントでは、プラグインは .mcp.json をプラグインのルートに置くか、plugin.json の中に書いてMCPサーバーを持てます。プラグインを有効にすると、そのサーバーは自動で起動します。

10月19日の実測では、プラグインの .mcp.json の形が2通りに分かれていました。1つは公式の例と同じく、トップに mcpServers があり、その下にサーバー名を置く形です。

もう1つは context7 というプラグインの .mcp.json の1つで、mcpServers で包まずにサーバー名 context7 を直に置く形でした。中身は command が npx と args です。

自分で .mcp.json を書くなら、僕は公式の例の mcpServers で包む形にそろえます。プラグインの中の書き方は作者ごとに違い、それを手本にすると読み違いのもとになるからです。

プラグインのMCPは /mcp からではなく、プラグインの導入と削除で増減します。入れたあとでも /mcp から個別にオフにはできます。

プラグインの探し方と入れる前の確かめ方は、Claudeのmarketplacesとプラグイン導入の実録に書きました。

2026年10月2日、プラグインに入っていた chrome-devtools は使わないと決めた

プラグインを入れると、.mcp.json のMCPも一緒に入ってきます。僕がそれを判断したのは、2026年10月2日に公開のプラグイン ECC（Everything Claude Code）を user スコープで入れたときです。

ECC の .mcp.json には、ブラウザを操作する chrome-devtools のMCPが入っていました。中身は npx chrome-devtools-mcp@1.10.1 を起動する設定です。

10月19日の実測でも、ECC の .mcp.json の mcpServers の下に同じサーバーが残っていました。

僕はこのMCPを使わないと決めました。僕の会社では、ブラウザの操作に使う道具を決めたルールがあり、このMCPはその対象だからです。接続台帳にも、9月に見送ったMCPと同じ扱いとして書き足しています。

この件で分かったのは、プラグインを入れる判断が、MCPを足す判断も兼ねている点です。僕なら入れる前に、プラグインの .mcp.json を開いて、どのサーバーが何のコマンドで起動するかを先に読みます。

Claude Code をこれから始める方は、Claude Codeの使い方（インストールから最初の1週間まで）から読むと順番がつかめます。プラグインやMCPは、基本の使い方に慣れてから足しても遅くありません。

まとめ

• .mcp.json は、プロジェクトのルートに置く project スコープのMCP設定ファイルで、バージョン管理に入れてチームで共有するためのもの
• 書き方はトップに mcpServers、その下にサーバー名ごとの設定。トークンやAPIキーは ${API_KEY} のように環境変数で渡し、値は直書きしない
• 対話の画面では使う前に承認が出て、claude mcp reset-project-choices でやり直せる。非対話の実行では確認なしで読み込まれるので、止めたいサーバーは disabledMcpjsonServers へ
• 僕の会社は2026年9月15日から原則 user スコープ。10月19日の実測で社内リポジトリは0件、プラグインの中は45件で、防いでいたのは .gitignore ではなく運用だった
• 僕なら、まず「この設定を他の人のパソコンでも動かしたいか」を決め、共有しないなら user か local、共有するなら秘密を書かない .mcp.json にします