Claude Code に MCP サーバーを追加する方法、claude mcp add・.mcp.json・スコープ・環境変数の渡し方

MCP(Model Context Protocol)は、AI エージェントに外部ツールやデータソースを接続するための共通規格です。Claude Code に MCP サーバーを追加すると、GitHub の Issue 操作、ブラウザ操作、データベース参照などを、Claude が自分で判断して実行できるようになります。

この記事では、claude mcp add コマンドによる追加手順、設定を「自分だけ」「このプロジェクトのチーム全員」「自分の全プロジェクト」のどこに置くかを決めるスコープ、チームで共有する .mcp.json にトークンを書かずに環境変数から渡す書き方、接続確認と権限設定までを順に整理します。

追加コマンドの基本形

stdio(ローカルでプロセスを起動する)方式

多くの MCP サーバーは npm パッケージとして配布され、npx で起動します。

claude mcp add <名前> -- <起動コマンド> [引数...]

例として Playwright(ブラウザ操作)サーバーを追加する場合は次のとおりです。-- より後ろが、サーバーを起動するコマンドです。環境変数が必要な場合は -e で渡します。

claude mcp add playwright -- npx @playwright/mcp@latest
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx -- npx -y @modelcontextprotocol/server-github

HTTP / SSE(リモートサーバー)方式

ホスティングされた MCP サーバーには --transport http で接続します。認証が必要なサーバーは、追加後に対話中の /mcp コマンドからブラウザ経由でログイン(OAuth)できます。

claude mcp add --transport http <名前> <URL>

スコープ、設定をどこに置くか

--scope オプションで、設定の保存先と共有範囲が変わります。見るべき点は保存先・共有範囲・優先順位の 3 つです。

スコープ	範囲	保存先	チームと共有	向いている用途
local(既定)	そのプロジェクトで自分だけ	~/.claude.json のそのプロジェクトのパスの下	されない	個人の試用、実験的な設定、バージョン管理に入れたくない認証情報を持つサーバー
project	プロジェクトの全員	プロジェクト直下の .mcp.json	される(バージョン管理経由)	プロジェクト共通のツール
user	自分のすべてのプロジェクト	~/.claude.json	されない	どこでも使う汎用ツール(検索、メモなど)

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

# チームで共有する(.mcp.json に書かれる)
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

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

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

同じサーバー名が複数の場所で定義されている場合、Claude Code は優先順位が最も高いソースの定義だけを使って 1 回接続します。フィールドがスコープをまたいで統合されることはありません。順位は local → project → user → プラグインが提供するサーバー → claude.ai のコネクタです。同じ名前を別のエンドポイントで複数のスコープに定義すると、claude mcp list の出力と /mcp で競合の警告が出ます。

.mcp.json の書き方とチーム共有

--scope project で追加すると、プロジェクト直下に次のような .mcp.json が生成されます。手で書いても構いません。このファイルはバージョン管理に入れてチームで共有します。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_MCP_URL:-https://mcp.example.internal/mcp}",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_MCP_TOKEN}"
      }
    }
  }
}

${VAR} で環境変数からトークンを渡す

.mcp.json は Git にコミットされるため、env にアクセストークンを直接書くとリポジトリの閲覧者全員に漏れます。Claude Code は .mcp.json の中で ${環境変数名} の形で環境変数を参照できるので、トークンの実体はシェル側に置きます。

記法	意味
${GITHUB_TOKEN}	環境変数 GITHUB_TOKEN の値に置き換わる
${VAR:-既定値}	VAR が未設定なら既定値を使う

展開は env だけでなく、command、args、url、headers の値でも使えます。環境変数はシェルの設定ファイル(~/.zshrc など)に export GITHUB_TOKEN="ghp_xxxx" の形で置いておくと、ターミナルから claude を起動したときに読まれます。VS Code 拡張から使う場合は VS Code 自体がその環境変数を持っている必要があるため、設定ファイルに書いたうえで VS Code を再起動するか、ターミナルから code . で起動してください。direnv を使うなら .envrc でディレクトリ単位に切り替えられます(.envrc は .gitignore に入れます)。

チームで同じサーバーを使うが認証は個人ごと、という場合はこの ${VAR} 方式が管理しやすく、自分しか使わないサーバーなら local スコープで登録する方が単純です。チームの運用ルールとしては、.mcp.json には ${VAR} だけを書いて値は絶対に書かない、README と .env.example に必要な環境変数の名前を並べる、トークンの権限は読み取り専用から始める、の 3 点を決めておきます。

project スコープには承認プロンプトがある

公式ドキュメントは「セキュリティ上の理由から、Claude Code は対話セッションで .mcp.json の project スコープのサーバーを使う前に承認を求める」と説明しています。承認をやり直すには claude mcp reset-project-choices を実行します。

プロンプトが出ない条件も明記されています。claude -p の実行、Agent SDK のセッション、クラウドセッションではプロンプトを表示できないため承認なしで読み込まれ、bypassPermissions モードで開始しユーザー設定か管理者設定に skipDangerousModePermissionPrompt がある場合もスキップされます。それでも特定のサーバーを読み込ませたくない場合は次の 3 つの手段があります。

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

接続を確認する

claude mcp list              # 登録済みサーバーと状態の一覧
claude mcp get github        # 個別の設定を表示
claude mcp remove github --scope local

対話中は /mcp を実行すると、各サーバーの接続状態、提供されているツール名、認証の要否が表示されます。「failed」になっている場合の確認順は次のとおりです。

1. 起動コマンドを単体で実行してエラーを見る(npx @playwright/mcp@latest)
2. 環境変数を使っているなら、ターミナルで echo $GITHUB_TOKEN を実行して値があるか確認する
3. Claude Code を起動したシェルと、環境変数を設定したシェルが同じか確認する
4. .mcp.json の変数名のスペルを確認する

ツールの実行許可を設定する

MCP のツールも、通常のツールと同じく実行前に確認が入ります。頻繁に使うものは settings.json の permissions で自動許可にできます。mcp__サーバー名 でサーバーの全ツール、mcp__サーバー名__ツール名 で個別に指定します。書き込み系のツールは ask に残しておくと安全です。

{
  "permissions": {
    "allow": [
      "mcp__playwright",
      "mcp__github__get_issue",
      "mcp__github__list_pull_requests"
    ],
    "ask": [
      "mcp__github__create_pull_request"
    ]
  }
}

permissions の詳細は settings.json と settings.local.json で permissions を設計する を、サーバーが公開するツールのうち使うものだけを有効にする方法は MCP サーバーのツールを個別に許可する を参照してください。

どのサーバーから入れるべきか

最初の 1 つは、日常の作業で「Claude に見せられなくて困っている情報」を提供するものを選ぶと効果を実感しやすいです。ブラウザの実画面(Playwright)、ライブラリの最新ドキュメント(Context7)、Issue や PR(GitHub)が定番です。具体的な候補は コーディング AI で最初に入れるべき MCP サーバー に、OAuth が必要な HTTP サーバーの接続手順は HTTP の MCP サーバーに OAuth でログインする にまとめています。秘密情報全般の扱いは AI コーディングツールに秘密情報を読ませないための設定 を参照してください。

まとめ

• claude mcp add 名前 -- 起動コマンド で stdio サーバー、--transport http でリモートサーバーを追加する
• スコープは local(既定、そのプロジェクトで自分だけ)/ project(.mcp.json でチーム共有)/ user(自分の全プロジェクト)。同じ名前は local → project → user の順で 1 つだけ使われる
• .mcp.json ではトークンを ${GITHUB_TOKEN} の形で環境変数から読ませ、値は書かない。${VAR:-既定値} で既定値を指定でき、env・args・url・headers で使える
• project スコープのサーバーは対話セッションで承認が必要。やり直しは claude mcp reset-project-choices
• /mcp と claude mcp list で接続状態を確認し、permissions で自動許可の範囲を決める

npx @playwright/mcp@latest

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server