Claude Code に MCP サーバーを追加する方法(claude mcp add と .mcp.json の使い分け)

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

この記事では、claude mcp add コマンドによる追加手順と、設定を「自分だけ」「このプロジェクトのチーム全員」「自分の全プロジェクト」のどこに置くかを決めるスコープの考え方を整理します。

追加コマンドの基本形

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

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

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

例:Playwright(ブラウザ操作)サーバーを追加する場合。

claude mcp add playwright -- npx @playwright/mcp@latest

-- より後ろが、サーバーを起動するコマンドです。環境変数が必要な場合は -e で渡します。

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

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

ホスティングされた MCP サーバーには --transport http で接続します。

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

認証が必要なサーバーは、追加後に対話中の /mcp コマンドからブラウザ経由でログイン(OAuth)できます。

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

--scope オプションで、設定の保存先と共有範囲が変わります。

スコープ	保存先	共有範囲	向いている用途
local(既定)	~/.claude.json(プロジェクトごとの項目)	自分・このプロジェクトのみ	個人の試用、認証情報を含むもの
project	リポジトリ直下の .mcp.json	チーム全員(Git で共有)	プロジェクト共通のツール
user	~/.claude.json	自分の全プロジェクト	どこでも使う汎用ツール

# チームで共有する
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

# 自分の全プロジェクトで使う
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp

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}"
      }
    }
  }
}

.mcp.json では ${環境変数名} の形で環境変数を参照できます。トークンそのものは書かず、各自のシェルの環境変数から読ませるのが原則です。

接続を確認する

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

対話中は /mcp を実行すると、各サーバーの接続状態、提供されているツール名、認証の要否が表示されます。「failed」になっている場合は、起動コマンドを手動で実行してエラーを確認するのが早道です。

npx @playwright/mcp@latest   # 単体で起動してエラーが出ないか確認

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

MCP のツールも、通常のツールと同じく実行前に確認が入ります。頻繁に使うものは settings.json の permissions で自動許可にできます。

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

mcp__サーバー名 でサーバーの全ツール、mcp__サーバー名__ツール名 で個別に指定します。書き込み系のツールは ask に残しておくと安全です。permissions の詳細は settings.json で permissions を設計する を参照してください。

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

最初の 1 つは、日常の作業で「Claude に見せられなくて困っている情報」を提供するものを選ぶと効果を実感しやすいです。ブラウザの実画面(Playwright)、ライブラリの最新ドキュメント(Context7)、Issue や PR(GitHub)が定番です。具体的な候補は コーディング AI で最初に入れるべき MCP サーバー にまとめています。

まとめ

• claude mcp add 名前 -- 起動コマンド で stdio サーバー、--transport http でリモートサーバーを追加する
• スコープは local(自分のみ)/ project(.mcp.json でチーム共有)/ user(自分の全プロジェクト)
• トークンは ${VAR} で環境変数から読ませ、.mcp.json に直接書かない
• /mcp と claude mcp list で接続状態を確認し、permissions で自動許可の範囲を決める