.mcp.jsonでMCPをチーム共有する——プロジェクトスコープと環境変数展開【CCA Foundations対策】

Anthropic Academyの「Claude Code in Action」コースをもとに解説しています。

MCPサーバーをチームで使うとき、claude mcp add でそれぞれが個別に追加する方法と、.mcp.json をリポジトリに含めてチーム全員が同じ設定を使う方法がある。d03では claude mcp add の手順を解説したが、チーム共有のユースケースでは設定が乖離していくという問題が残る。

この記事でわかること：

claude mcp add のユーザースコープと .mcp.json のプロジェクトスコープの違い
${ENV_VAR} 構文で環境変数を展開してシークレットをコミットせずに共有する方法
チームオンボーディングのベストプラクティス

2つのスコープ：ユーザー vs プロジェクト

claude mcp add（ユーザースコープ）

claude mcp add --scope user github-mcp npx @modelcontextprotocol/server-github

--scope user（省略するとデフォルト）で追加されたMCPサーバーは、そのマシンのユーザー設定として保存される。バージョン管理対象外のため、リポジトリをクローンした他の開発者には引き継がれない。

チームで6人が個別に追加した場合、バージョンやパラメータが少しずつ異なる6つの設定が存在することになる。新しいメンバーが加わるたびに手動でセットアップが必要になり、設定ドリフトが発生しやすい。

.mcp.json（プロジェクトスコープ）

プロジェクトのルートに .mcp.json を置き、バージョン管理に含める。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

このファイルをリポジトリにコミットすると、git clone または git pull した全員が同じMCP設定を受け取る。設定の一元管理ができるため、チームの一貫性が保たれる。

環境変数展開：シークレットをコミットしない

.mcp.json にトークンをそのまま書くとシークレットがリポジトリに入る。${VARIABLE_NAME} 構文を使うと、Claude Codeが実行時に環境変数を展開する。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

.mcp.json はコミット対象だが、実際のトークン値は各開発者のローカル環境変数として管理する。リポジトリにはプレースホルダーだけが入る。

各開発者のセットアップは、シェルの設定ファイル（.bashrc・.zshrc・.env）に変数を追加するか、CI/CDのシークレット設定に追加するだけでよい。

チームオンボーディングのパターン

プロジェクトに .mcp.json を含めた場合の標準的な構成：

リポジトリに含めるもの：

.mcp.json：MCPサーバーの定義（環境変数プレースホルダーあり）
README.md：必要な環境変数の一覧とセットアップ手順

含めないもの（.gitignoreで除外）：

.env：実際のトークン値
~/.claude/ 内の設定：ユーザー個別のローカル設定

READMEに必要な変数を明記しておくことで、新しいメンバーは「どの変数を用意すればよいか」を把握してオンボーディングできる。

## セットアップ

以下の環境変数を設定してください：

- `GITHUB_TOKEN`：GitHub Personal Access Token（repo, read:org スコープ）
- `SLACK_BOT_TOKEN`：Slack Bot Token（channels:read, chat:write スコープ）

ユーザースコープを使うケース

プロジェクトスコープが常に正解というわけではない。個人ワークフロー専用のMCPサーバー（ローカルメモ管理・個人カレンダー連携など）はリポジトリと無関係なため、ユーザースコープで追加するのが適切だ。

ケース	スコープ
チームで共通のGitHub・Slack連携	プロジェクト（`.mcp.json`）
個人的なタスク管理ツール	ユーザー（`claude mcp add`）
社内全チームで使うツール	ユーザー（各自セットアップ）または社内テンプレート

まとめ

claude mcp add（ユーザースコープ）：個人設定として保存。チームに引き継がれない
.mcp.json（プロジェクトスコープ）：バージョン管理対象。クローンした全員が受け取る
${GITHUB_TOKEN} 形式で環境変数を展開する：シークレットをコミットせずに設定値を共有できる
「チーム全員が一貫した設定を使いつつ各自のクレデンシャルを使う」要件には .mcp.json + 環境変数展開の組み合わせが適切

ここまでがClaude Code実践編の補足。次は Claude API編の補足として、Batch APIの設計制約を解説する。