Claude Code VS Code 拡張で MCP を使う設定｜CLI と /mcp の手順

前提: VS Code 拡張は「サーバー追加=CLI、管理=/mcp」の二刀流 {#prerequisite}

Claude Code の VS Code 拡張は、MCP まわりの操作を CLI とチャットパネルで明確に分担 しています。公式ドキュメントの機能比較表でも「MCP サーバー設定」は CLI が「はい」、VS Code 拡張は「部分的(CLI 経由でサーバーを追加。チャットパネルで /mcp を使用して既存のサーバーを管理)」と明記されており、追加だけは必ず統合ターミナル経由になります。

前提として VS Code 1.98.0 以上と Anthropic アカウントが必要で、拡張機能をインストールした直後の状態でも、claude バイナリは拡張に同梱されているため別途インストールは不要です。統合ターミナルを Ctrl+\`` / Cmd+`` で開いた瞬間から claude mcp add が叩けます。逆に言うと「拡張パネルから GUI で追加できない」のは仕様で、Cursor などの他拡張のクセを持ち込まないことが重要です。

出典: VS Code で Claude Code を使用する — Claude Code Docs

MCP サーバーを追加する CLI 手順 {#cli-add}

VS Code の統合ターミナルで claude mcp add を実行します。基本構文は次のとおりです。

claude mcp add --transport <stdio|http|sse> <name> <url-or-command> [--header "Key: Value"]

公式ドキュメントが例示しているリモート HTTP MCP の追加コマンドはこちらです。

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

ポイントは 3 つあります。

1. --transport を 明示する(stdio は省略可だがチーム共有では明示を推奨)
2. <name> はチャット内で mcp__<name>__<tool> の prefix になるので、短く一意に
3. 認証ヘッダーは --header 複数指定可、$ENV_VAR 展開もできるので生トークンを履歴に残さない運用にする

追加後は 拡張機能の再起動不要 で、Claude にツール名を伝えれば即座に呼べます。

出典: VS Code で Claude Code を使用する — Claude Code Docs / MCP で外部ツールに接続する

/mcp ダイアログで状態を管理する {#mcp-panel}

サーバーを追加したあとの 有効化/無効化・再接続・OAuth 再認可 は、VS Code を離れずにチャットパネルから操作します。プロンプトボックスで /mcp と入力すると「MCP 管理ダイアログ」が開き、登録済みサーバーの一覧と接続状態(connected / failed / needs auth)が表示されます。

このダイアログでできる主な操作はこちらです。

1. 個別サーバーの有効/無効トグル(ワークスペース単位)
2. 切れた接続の手動再接続
3. OAuth フロー再開(token 期限切れ時)
4. ツール一覧の確認(モデルが見えているもののみ)

「claude mcp add で追加したのに /mcp に出てこない」場合の多くは、~/.claude/settings.json の enabledMcpjsonServers か disabledMcpjsonServers で抑止されているケースです。設定共有は拡張機能と CLI で同じファイルを見るので、片方で無効化したものはもう片方にも反映されます。

スコープと .mcp.json でプロジェクト共有する {#scope-mcpjson}

claude mcp add には 3 つのスコープ があります。チーム配布を考えるなら、最初からスコープを決めて追加します。

1. --scope user (デフォルト) — ~/.claude.json に保存、全プロジェクトで有効
2. --scope project — リポジトリ直下に .mcp.json を生成、git で共有可能
3. --scope local — そのリポジトリかつ自分だけ(チーム共有しない PoC 向け)

プロジェクト共有用のコマンド例はこちらです。

claude mcp add --scope project --transport stdio mydb \
  -- node ./mcp-servers/mydb/index.js

.mcp.json をコミットしておけば、別の開発者が同じリポジトリで Claude Code を開いた瞬間に MCP サーバーが提案され、各自の /mcp で承認するだけで使えます。シークレットは .mcp.json に直接書かず、${env:VAR} 形式で参照 するのが鉄則です。プラグイン経由の MCP 追加と組み合わせると、リポジトリを clone した瞬間に MCP 環境が揃う体験を作れます。

--mcp-config で構成を切り替える {#mcp-config}

開発用フル構成と CI 用ミニマル構成を切り替えたい場合は、起動時に --mcp-config <file> を渡して MCP 設定ファイルを差し替え できます。VS Code の統合ターミナルから次のように起動します。

claude --mcp-config ./.claude/mcp.lightweight.json

このフラグは .mcp.json の代わりに指定ファイルを読み込むため、

1. 本番調査用フル構成(GitHub・Sentry・Datadog 全部入り)
2. コーディング集中用ライト構成(Figma と filesystem だけ)
3. CI/オフライン用ゼロ構成(MCP なし、純粋なコード補助のみ)

をワンキー切り替えできます。zenn.dev/kuxu の解説でも紹介されている運用パターンで、トークン消費とレイテンシを抑えたいときに有効です。VS Code のタスクや keybinding に Claude Code (light) のようなコマンドを登録しておくと、起動 1 秒で構成を切り替えられます。

出典: Claude Code で MCP を快適に使う設定術 --mcp-config(zenn.dev/kuxu)

内蔵 ide サーバーの正体と hook 設定 {#ide-server}

VS Code 拡張がアクティブな間、CLI 側からは ide という名前のローカル MCP サーバーが自動接続 しています。差分ビューアの起動、@-メンション時の選択範囲取得、Jupyter ノートブックでのセル実行は、すべてこの ide サーバー経由です。

/mcp には現れない仕様ですが、組織で PreToolUse hook を使って MCP ツールをホワイトリスト化している場合は、次の 2 つを許可リストに入れる必要があります。

1. mcp__ide__getDiagnostics — VS Code の問題パネル(エラー/警告)を返す、読み取り専用
2. mcp__ide__executeCode — アクティブな Jupyter ノートブックでセルを実行、毎回 Quick Pick で確認

executeCode は静かに走らない設計で、毎回 VS Code の Quick Pick で Execute/Cancel を尋ねます。hook で許可してもこの確認は省略できないため、信頼できないコードを扱うときも安全側に倒れます。トランスポートは 127.0.0.1 限定でランダム高ポートを使い、認証トークンは ~/.claude/ide/ 配下に 0600 で書かれるため、同一マシンの他ユーザーからは触れません。

出典: VS Code で Claude Code を使用する — Claude Code Docs / 組み込み IDE MCP サーバー

代表的なコネクター追加レシピ {#recipes}

VS Code の Claude Code でよく使われる MCP 追加コマンドを 4 つまとめます。

1. GitHub(リモート HTTP)

   claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
     --header "Authorization: Bearer $GITHUB_PAT"
   

2. Figma(リモート HTTP、ログイン後のコンテキスト)

   claude mcp add --transport http figma https://api.figma.com/v1/mcp \
     --header "X-Figma-Token: $FIGMA_TOKEN"
   

3. filesystem(ローカル stdio、検索の高速化)

   claude mcp add --transport stdio fs -- npx -y @modelcontextprotocol/server-filesystem .
   

4. Postgres(ローカル stdio、開発用 DB)

   claude mcp add --transport stdio pg \
     -- npx -y @modelcontextprotocol/server-postgres "postgres://user:pass@localhost/dev"
   

実装の組み合わせ事例は Qiita の Figma MCP 連携記事が詳しいです。VS Code + Claude Code + Figma MCP の構成で、デザインカンプから直接コード化する流れがそのまま再現できます。

出典: VSCode + Claude Code + Figma MCP で始める AI コーディング環境構築ガイド(Qiita) / Windows の VSCode で Claude Code と Serena MCP を連携させる完全手順(Qiita)

うまく動かないときのチェックリスト {#troubleshooting}

「ツールが Claude から見えない」「/mcp で failed になる」ときは、次の順番で切り分けると 9 割は片付きます。

1. 認証トークンの期限切れ — /mcp で needs auth 表示なら、ダイアログから OAuth を再実行
2. transport の取り違え — リモート API なのに stdio で登録していないか claude mcp list で確認
3. 設定の無効化 — ~/.claude/settings.json の enabledMcpjsonServers / disabledMcpjsonServers を見直す
4. .mcp.json の env 展開漏れ — ${env:GITHUB_PAT} のような参照を直書きしていないか確認
5. VS Code の再読込 — コマンドパレットで「Developer: Reload Window」を実行(ide サーバーが再生成される)
6. Restricted Mode — Workspace Trust が制限モードだと拡張機能ごと無効、ワークスペース信頼を有効化
7. 拡張機能のログ — コマンドパレットで「Claude Code: Show Logs」、認証エラーとポート競合はここに出る

VS Code を離れて CLI を直接叩きたい場合は、統合ターミナルで claude を実行すれば現在のセッションをそのまま続行できます。claude --resume で履歴ピッカーが出るので、拡張で詰まったセッションの続きを CLI 側で動かして MCP の挙動を切り分ける、という運用も有効です。

出典: VS Code で Claude Code を使用する — Claude Code Docs / 一般的な問題を修正する

VS Code の Claude Code 拡張で MCP を扱うコツは、追加は CLI、運用は /mcp、共有は .mcp.json、切り替えは --mcp-config、内蔵 ide サーバーだけ別枠で意識する という 5 点に尽きます。本記事の手順どおりに claude mcp add を 1 度だけ通せば、あとはチャットパネルから一切ターミナルに戻らずに MCP 環境を運用できます。