VS Codeのmcp.jsonの書き方 — .mcp.jsonとの違いと置き場所

VS CodeのMCP対応とは — Claude Code拡張のMCP設定と何が違うか

VS Code本体は、GitHub Copilot Chatの機能としてMCP(Model Context Protocol)サーバーに対応しています。同じMCPサーバーをClaude・ChatGPT・Cursorに繋いだ場合の違いは別記事にまとめています。MCPは外部ツールやデータソースをAIに接続するオープン標準規格です。VS Code上では、ファイル操作・データベース接続・外部API呼び出しといったツールをチャットから直接呼び出せるようになります。プロトコル自体の全体像はMCPとはで扱っており、本記事はVS Code本体での設定・管理手順に絞ります。

ここで注意が必要なのは、VS Code本体のMCP設定とClaude Code拡張のMCP設定は別物という点です。両方ともVS Codeのエディタ上で動きますが、設定ファイルの場所も、対象になるチャットクライアントも独立しています。

Claude Codeのclaude mcp addによるMCP設定はClaude Code MCP設定ガイド、Claude Code自体のVS Code拡張の使い方はClaude Code VS Code拡張機能の使い方にまとめています。この記事が扱うのはVS Code本体(Copilot Chat)側のMCP設定です。Claude Codeを使っていない環境でも通用します。表の最終行のとおり、.mcp.jsonだけは両者が共有できるので、その手順は後半で実機の出力つきで扱います。

mcp.jsonと.mcp.jsonはどこに置くか — 名前が似た4つのファイル

「mcp.json」と「.mcp.json」は別のファイルです。VS Codeが読む設定ファイルは次の4つで、最上位のキーが違います。

先頭にドットが付き、.vscodeの外に置くのが.mcp.jsonです。Claude Codeのプロジェクトスコープと同じ名前なので、Claude Codeと設定を共有するときはこちらを使います。ガイド付きの追加フローで.mcp.jsonを選ぶには、実験的設定chat.mcp.workspaceRootConfig.enabledを有効にします。書式の違いは「mcp.jsonの書き方」と「Claude Codeと同じ.mcp.jsonを共有する」の節で扱います。

前提条件

必要なのはVS Codeと、Copilotを有効にしたGitHubアカウントの2つです。MCPサーバーはCopilot ChatのAgentモードやチャットビューから呼び出す前提の機能なので、Copilotが有効になっていないとインストールしたサーバーのツールを使えません。

• VS Code本体(最新の安定版を推奨)
• GitHubアカウントでのサインインとCopilotの有効化(プランが無ければCopilot Free)。現行のVS CodeではAI機能が組み込みで、Copilot Chat拡張機能を別途入れることは必須になっていません
• ローカルサーバーを使う場合はNode.js等、サーバーの実行環境(npxで動くサーバーが大半)

Claude Codeを併用している場合でも、この前提条件はClaude Codeの導入状況と無関係です。VS Code本体のMCP設定はCopilot Chat単体で完結します。

MCPサーバーをインストールする3つの方法

MCPサーバーの追加は、拡張機能ギャラリーからの検索インストール、mcp.jsonの手動編集、コマンドラインの3経路があります。まず一番手早いギャラリー経由の手順を確認します。

拡張機能ビュー(⇧⌘X / Ctrl+Shift+X)を開き、検索欄に@mcpと入力すると、利用可能なMCPサーバーの一覧が表示されます。個別サーバー名まで絞りたい場合は@mcp playwrightのように続けて入力します。一覧からInstallを選ぶとユーザープロファイルにインストールされ、初回起動時に「このサーバーを信頼するか」の確認ダイアログが出ます。

ワークスペース単位でチームと共有したい場合は、サーバーを右クリックしてInstall in Workspaceを選びます。これにより.vscode/mcp.jsonが更新され、バージョン管理に含めればチーム全員が同じMCPサーバー構成を使えます。

コマンドラインからも追加できます。code --add-mcpにJSON形式のサーバー設定を渡すと、ユーザープロファイルに登録されます。--mcp-workspaceを併用するとユーザープロファイルではなくワークスペースやフォルダーに登録されます。VS Code 1.99.1のcode --helpには次のように出ます。

code --help | grep -A6 -e '--add-mcp'

  --add-mcp <json>       Adds a Model Context Protocol server definition to the
                         user profile, or workspace or folder when used with
                         --mcp-workspace. Accepts JSON input in the form
                         '{"name":"server-name","command":...}'

登録の実例は次のとおりです。

code --add-mcp "{\"name\":\"my-server\",\"command\":\"uvx\",\"args\":[\"mcp-server-fetch\"]}"

mcp.jsonの書き方 — stdioとHTTP/SSEの設定例

mcp.jsonはservers / inputs / sandboxの3セクションで構成される設定ファイルです。サーバーの接続方式によって書き方が変わります。ローカルで動くサーバーはstdio(標準入出力)、リモートのサーバーはHTTPかSSE(Server-Sent Events)を使います。

stdioサーバーで必須なのはtypeとcommandの2フィールドだけです。以下はローカルパッケージをnpx経由で起動する最小構成です。

{
  "servers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

リモートサーバーはtypeにhttpかsseを指定し、urlでエンドポイントを指定します。VS CodeはまずHTTP Streamトランスポートを試し、対応していなければSSEにフォールバックします。認証が必要なサーバーにはheadersかoauthを追加します。

{
  "servers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "example-client-id"
      }
    }
  }
}

oauthを設定すると、初回接続時にブラウザが開いて認可フローが自動的に進みます。APIキーをそのまま書き込みたくない場合は、inputs配列で入力変数を定義し、${input:変数名}の形でサーバー設定から参照します。入力タイプは自由入力のpromptString、選択式のpickString、コマンド実行結果を使うcommandの3種類です。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "Perplexity API Key",
      "password": true
    }
  ],
  "servers": {
    "perplexity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "PERPLEXITY_API_KEY": "${input:perplexity-key}"
      }
    }
  }
}

password: trueを付けると、入力値が画面上でマスクされます。サーバー名はcamelCase(uiTestingのような形)で、空白や特殊文字を避けるのが公式の命名規則です。

Remote-SSHやWSLなどでリモートに接続している場合は、実行場所に注意が要ります。ユーザープロファイルに入れたサーバーはローカルで動きます。リモート側で動かしたいときは、ワークスペースのmcp.jsonか、MCP: Open Remote User Configurationで開くリモートのユーザー設定に定義します。

Claude Codeと同じ.mcp.jsonを共有する

ワークスペース直下の.mcp.jsonは、互換ツール間で使えるポータブル形式です。手元のClaude Code(v2.1.285)でプロジェクトスコープに書き出させると、次のとおり冒頭の表と同じmcpServers形式になりました。

claude mcp add -s project memory -- npx -y @modelcontextprotocol/server-memory
cat .mcp.json

Added stdio MCP server memory with command: npx -y @modelcontextprotocol/server-memory to project config
File modified: <作業ディレクトリ>/.mcp.json
{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {}
    }
  }
}

上の出力はClaude Code側が書いたファイルの実物です。一方、このファイルをVS Code側が実際に読み込むかどうかは、公式ドキュメントの記述を根拠にしており、手元の環境(VS Code 1.99.1)では起動して確かめていません。試すときは、envに機密値を直接書かないことだけ先に決めておくと安全です。

ツール呼び出し以外にできること — リソース・プロンプト・MCP Apps

MCPサーバーが提供できる機能はツール呼び出しだけではありません。VS Codeはリソース・プロンプト・MCP Appsの3種類にも対応しており、MCP Appsの対応クライアント一覧とExtensionsの仕組みは他クライアントとの差も扱っています。

いずれもサーバー側が対応している場合にのみ使えます。リソースとプロンプトはサーバーを入れた時点で追加設定なしに使えます。MCP Appsは実験的機能で、chat.mcp.apps.enabled設定で有効・無効を切り替えます(VS CodeとClaude DesktopのMCP Apps対応差も参照)。

サンドボックスと信頼設定で安全に使う

ローカルのMCPサーバーは任意のコードを実行できるため、VS Codeは初回起動時に信頼確認ダイアログを出します。ダイアログのリンクからサーバー設定を開き、コマンドや引数を確認してから承認します。拒否するとサーバーは起動せず、チャットはそのサーバーのツールなしで続きます。

信頼の扱いは設定の置き場所で変わります。ワークスペースのMCPサーバーはWorkspace Trustを引き継ぎ、ワークスペースを信頼済みにすると、.vscode/mcp.jsonとルート直下の.mcp.jsonのサーバーは個別の確認なしに起動します。設定が書き換わった後も同様です。制限モードではワークスペースのMCP設定自体がブロックされます。それ以外の場所のサーバーは、初回起動時と設定変更時に確認が出ます。

信頼済みの状態をやり直すには、コマンドパレットでMCP: Reset Trustを実行します。このコマンドはWorkspace Trustには影響しません。

macOSとLinuxでは、stdioサーバーをサンドボックス化してファイルシステムとネットワークへのアクセスを制限できます。サーバー設定に"sandboxEnabled": trueを追加し、sandboxオブジェクトで許可・拒否ルールを定義します。

{
  "servers": {
    "myServer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "sandboxEnabled": true
    }
  },
  "sandbox": {
    "filesystem": {
      "allowWrite": ["${workspaceFolder}"],
      "denyRead": ["${userHome}/.ssh"]
    },
    "network": {
      "allowedDomains": ["api.example.com", "*.cdn.example.com"]
    }
  }
}

サンドボックスが有効なサーバーは、ツール呼び出しのたびに確認ダイアログを出さず自動承認されます。制御された環境で動く前提だからです。サンドボックスが使えるのはmacOSとLinuxだけで、Windowsでは利用できません。

複数のMCPサーバーを管理する — 有効化・無効化・トラブルシュート

インストール済みのMCPサーバーは3つの経路から管理できます。拡張機能ビューの「MCP SERVERS - INSTALLED」セクション、mcp.jsonエディタのインラインアクション、コマンドパレットのMCP: List Serversです。個別サーバーの右クリックメニューから、開始・停止・ログ表示・アンインストール・キャッシュ済みツールのクリアが行えます。

有効/無効の切り替えはmcp.json本体とは別に保存されるため、チームで共有する設定ファイルを汚しません。個人的に一時停止したいサーバーがあっても、コミット対象のワークスペース設定には影響しません。

複数のデバイスで同じ構成を使いたい場合は、Settings Syncを有効にし、同期対象の一覧で「MCP Servers」をオンにします。MCPサーバーの構成がデバイス間で同期されます。

使えるサーバーはchat.mcp.access設定で制御できます。組織はGitHubのポリシーでMCPサーバーへのアクセスを一元管理できます。サーバーがバックグラウンドで行うリクエスト(サンプリング)に、どのモデルを公開するかはchat.mcp.serverSamplingで設定します。

chat.mcp.discovery.enabledを使うと、他のアプリが持つMCPサーバー設定を検出して再利用できます。検出元はClaude Desktop、GitHub Copilot CLI、Cursor(グローバルとワークスペース)、Windsurfの5種で、すべて既定でオフです。

一覧にClaude Code独自の~/.claude.jsonは入っていません。個人用のClaude Code設定を持ち込みたいときは、.mcp.jsonに書き出して共有する経路を使います。

chat.mcp.autostart(実験的機能)は、チャットの送信時にVS Codeがサーバーを自動起動する範囲を決めます。

無効化したサーバーとエラー状態のサーバーは対象外です。Agent Hostのセッションは別管理なので、neverでもAgent Host側のMCPサーバーは起動します。

よくあるつまずき

Dockerサーバーが起動しない

stdioサーバーの実体がDockerコンテナの場合、-d(デタッチ)オプションを付けるとVS Codeとの通信が成立しません。コンテナはフォアグラウンドで動かす必要があります。

信頼したはずのリポジトリで確認なしに起動する

ワークスペースを信頼済みにすると、そのワークスペースのMCPサーバーは個別の確認なしに起動します。他人のリポジトリを開くときは、信頼する前に.vscode/mcp.jsonと.mcp.jsonのコマンドを読んでください。制限モードのままなら起動しません。

ツール一覧が古いまま更新されない

サーバー側でツールの定義を変えても、VS Code側にキャッシュされた一覧が残ることがあります。コマンドパレットからMCP: Reset Cached Toolsを実行すると解消します。自作サーバーで挙動そのものが怪しい場合は、VS Codeに繋ぐ前にMCP Inspectorの使い方でサーバー単体の応答を確認すると原因の切り分けが早くなります。

Agent Hostがワークスペースの.vscode/mcp.jsonを読まない

VS CodeのAgent Host機能は.vscode/mcp.jsonを直接読みません。対話入力が必要な${input:...}変数を含む設定を除き、VS Code側からAgent Hostへ設定が転送される形です。Agent Hostや他のCopilotツールと共有したい設定は、ワークスペース直下の.mcp.json(.vscode/配下ではない点に注意)か、ユーザーの~/.copilot/mcp-config.jsonに置きます。ファイル名が似ているので混同しやすい箇所です。

上記のいずれにも当てはまらない場合は、チャットビューのエラー通知からShow Outputを選ぶか、MCP: List Serversで対象サーバーを選んでShow Outputを実行すると、サーバー自体が出力したログを確認できます。

まとめ

VS Code本体のMCP設定はCopilot Chat側のmcp.jsonで完結し、Claude Codeの~/.claude.jsonやclaude mcp add(local・userスコープ)とは別物です。共有できるのはルート直下の.mcp.jsonで、Claude Code側が書き出した実物はmcpServers形式でした。チームで共有する設定は.mcp.jsonに、VS Code固有の入力変数やサンドボックスが要る設定は.vscode/mcp.jsonに置き分ける選択肢があります。

よくある質問

プロファイルごとに別のMCPサーバー構成を持てますか

持てます。複数プロファイルを使う場合、プロファイルごとに独立したユーザーmcp.jsonを持てます。仕事用と検証用で分けていれば、MCPサーバーの構成もプロファイル単位で切り替わります。

リモートMCPサーバーでOAuth以外の認証方法は使えますか

headersフィールドにAuthorization: Bearer ${input:api-token}のようなヘッダーを設定すれば、OAuthを実装していないAPIキー方式のサーバーにも接続できます。