CCHub
← Back
· Tips · 1時間前

Claude Code の MCP 連携ガイド：claude mcp add・スコープ・.mcp.json の承認と認証

🦉
kenji_404
Builder · Lv.1

Claude Code の MCP 連携ガイドとして、claude mcp add のトランスポート指定、local・project・user の3スコープ、.mcp.json の共有と承認、OAuth 認証、出力上限とタイムアウト、/mcp での状態確認とつまずきやすい点を公式ドキュメントに沿って整理する。

MCP をつなぐと何が変わるのか

MCP（Model Context Protocol）は、AI とツールをつなぐためのオープンな標準だ。公式ドキュメントは、課題管理や監視ダッシュボードなど別のツールからチャットへデータを貼り付けている場面を、サーバーを接続する目安として挙げている。接続後の Claude は、貼り付けられた断片ではなく相手のシステムを直接読み、操作できる。

用途の例には、JIRA の課題を実装して GitHub に PR を出す、Sentry の監視データを確認する、PostgreSQL に問い合わせる、といったものが並ぶ。便利さの裏返しとして、公式は接続前にそのサーバーを信頼できるか確かめるよう警告しており、外部コンテンツを取得するサーバーはプロンプトインジェクションのリスクにつながるとしている。どのサーバーをつなぐかは、機能より先に権限と入力元で判断したい。

以下の仕様は 2026 年 9 月時点の公式ドキュメントに基づく。版ごとの変更が多いので、挙動が違う場合はまずバージョンを確かめたい。

claude mcp add とトランスポートの選び方

サーバーの追加は claude mcp add で行う。接続方式は HTTP、SSE、stdio、WebSocket の4つで、公式はリモートサーバーに HTTP を推奨している。SSE は非推奨で、v2.1.265 以降は HTTP で追加すれば、サーバーが受け付けない場合に SSE へ自動で切り替わる。

```bash # リモートの HTTP サーバー（公式の例: Notion） claude mcp add --transport http notion https://mcp.notion.com/mcp

# ローカルの stdio サーバー（公式の例: Airtable） claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \ -- npx -y airtable-mcp-server ```

stdio サーバーで引っかかりやすいのが `--` の位置だ。`--` より前は Claude Code のオプション、後ろはサーバーの起動コマンドとしてそのまま渡される。省くとサーバー側のフラグを Claude Code が自分のものとして読もうとする。

```bash # NG: --port を Claude Code が自分のオプションとして読もうとする claude mcp add --env KEY=value --transport stdio myserver python server.py --port 8080

# OK: -- 以降は python server.py --port 8080 としてそのまま実行される claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 ```

もう一点、`--env` は複数の KEY=value を受け取るため、直後にサーバー名を置くとそれも値の組として読まれて拒否される。上の OK 例のように、`--env` とサーバー名の間に `--transport stdio` などを挟む。

WebSocket は `--transport` で指定できず、`.mcp.json` か claude mcp add-json で登録する。他のクライアント向けの `mcpServers` ブロックを持ち込む場合も add-json で、渡すのは外側のラッパーではなく、サーバー名キーの値のオブジェクトだ。`url` はあるのに `type` がないエントリは stdio として読まれて失敗するので、`"type": "http"` などを補ってから登録する。claude mcp コマンドで追加するサーバー名に使えるのは英数字・ハイフン・アンダースコアだけだ。

スコープ：local・project・user と .mcp.json

追加したサーバーをどこに保存するかは `--scope`（短縮形 `-s`）で決まる。3つのスコープの違いは、読み込まれる範囲とチームで共有されるかどうかだ。

| スコープ | 読み込まれる範囲 | チーム共有 | 保存先 | | - | - | - | - | | local（既定） | 現在のプロジェクトのみ | しない | `~/.claude.json` | | project | 現在のプロジェクトのみ | バージョン管理経由でする | プロジェクト直下の `.mcp.json` | | user | 自分の全プロジェクト | しない | `~/.claude.json` |

local は `~/.claude.json` の中の、そのプロジェクトのパスの下に書き込まれる。資格情報を含む個人用や試験的な設定は local、全プロジェクトで使う個人ツールは user、チームに配るものは project という住み分けになる。

project スコープで追加すると `.mcp.json` が作成または更新され、これをコミットすればチームが同じ構成を得られる。API キーを直書きしないために使うのが環境変数の展開で、`${VAR}` と、未設定時の既定値を指定する `${VAR:-default}` が `command`・`args`・`env`・`url`・`headers` で使える。

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

注意点が二つある。既定値のない変数が未設定だと、設定は読み込まれるものの `${VAR}` の文字列がそのまま使われ、claude mcp list と /mcp に警告が出る。さらに、リモートサーバーの `url` と `headers` では `ANTHROPIC_API_KEY` や `ANTHROPIC_AUTH_TOKEN`、`NPM_TOKEN` などの資格情報系の変数が、設定済みでも警告なしに空として扱われる。リポジトリやプラグイン経由で Claude Code の資格情報が外部へ送られるのを防ぐ措置で、渡したい場合は別名の変数へ値を移して参照する。

同じサーバーが複数の場所にあれば local、project、user、プラグイン、claude.ai のコネクタの順で優先され、最上位のエントリが丸ごと使われる。3スコープ間は名前で、プラグインとコネクタは接続先の URL やコマンドで重複を判定する。

.mcp.json の承認とセキュリティ上の注意

.mcp.json はリポジトリに入るファイルなので、自分以外が定義したサーバーも含まれうる。Claude Code はセキュリティ上の理由から、対話セッションでは project スコープのサーバーを使う前に承認を求める。承認の結果は `.claude/settings.local.json` に `enabledMcpjsonServers` や `enableAllProjectMcpServers` として記録され、選択をやり直したいときは claude mcp reset-project-choices を実行する。

では、承認済みの設定をコミットしておけば全員の手間が省けるのか。信頼前のフォルダでは効かない。ワークスペースの信頼ダイアログを受け入れるまで、リポジトリにコミットされた `.claude/settings.json` の承認設定は無視され、サーバーは `⏸ Pending approval` のまま止まる。**リポジトリは自分自身のサーバーを承認できない**という設計で、ユーザー設定の `~/.claude/settings.json`、管理設定、`--settings` で渡した設定の承認は信頼前でも有効だ。逆に `disabledMcpjsonServers` による拒否はどの設定ファイルからでも効き、承認より優先される。

見落としやすいのは非対話の実行だ。claude -p、Agent SDK、クラウドセッションでは承認プロンプトを出せず、project スコープのサーバーは確認なしで読み込まれる。止める手段として公式は `disabledMcpjsonServers` への登録、`--setting-sources` によるプロジェクト設定の除外、`--strict-mcp-config` で `--mcp-config` に渡したサーバーだけを使う方法を挙げている。見知らぬリポジトリを CI で扱うなら、どれかを入れておきたい。

認証：OAuth、ヘッダー、headersHelper

OAuth 2.0 が必要なリモートサーバーは、追加後に /mcp を開いてブラウザでログインする。セッションに入らずシェルから済ませたい場合は claude mcp login を使い、SSH 接続などでブラウザがない環境では認可 URL が表示される。

続きを読むには

無料でアカウント作成

CCHub は Claude Code 開発者のための日本語コミュニティです。

#claude-code#MCP#セキュリティ#設定

コメント