MCP 開発者ガイド
Model Context Protocol (MCP) は、AI モデルが統一されたインターフェイスを介して外部ツールやサービスと対話できるようにするオープン スタンダードです。Visual Studio Code は完全な MCP 仕様を実装しており、VS Code で AI エージェントの機能を拡張するためのツール、プロンプト、リソースを提供する MCP サーバーを作成できます。
このガイドでは、VS Code およびその他の MCP クライアントとシームレスに連携する MCP サーバーを構築するために必要なすべての情報について説明します。
VS Code の MCP サポートは現在プレビュー中です。
MCP サーバーを使用する理由
VS Code のチャットを言語モデルツールで拡張するために MCP サーバーを実装することには、次の利点があります。
- エージェントモードを拡張: ユーザープロンプトへの応答の一部として自動的に呼び出される、専門的でドメイン固有のツールでエージェントモードを拡張します。たとえば、データベースのスキャフォールディングとクエリを有効にして、LLM に関連するコンテキストを動的に提供します。
- ローカルおよびリモートシナリオ向けの柔軟なデプロイオプション。
- 異なるツールやプラットフォーム間で MCP サーバーを再利用します。
次のシナリオでは、Language Model API を使用して言語モデルツールを実装することを検討できます。
- 拡張機能 API を使用して VS Code と深く統合したい場合。
- Visual Studio Marketplace を使用してツールと更新プログラムを配布したい場合。
VS Code に MCP サーバーを追加する
ユーザーは VS Code 内でさまざまな方法で MCP サーバーを追加できます。
- ワークスペース構成: ワークスペース内の
.vscode/mcp.jsonファイルでサーバー構成を指定します。 - グローバル構成: ユーザーのプロファイルでサーバーをグローバルに定義します。
- 自動検出: VS Code は Claude Desktop のような他のツールからサーバーを検出できます。
- 拡張機能: VS Code 拡張機能は MCP サーバーをプログラムで登録できます。
さらに、ユーザーは、VS Code Web サイトの MCP ギャラリーで使用されている特別な URL (vscode:mcp/install) を開くことで MCP のインストールをトリガーできます。ユーザーは、拡張機能ビューの MCP ビューからギャラリーに直接アクセスできます。
最後に、--add-mcp コマンドライン オプションを使用して、コマンドラインから MCP サーバーをインストールします。
MCP サーバーを管理する
VS Code の拡張機能ビュー (⇧⌘X (Windows、Linux Ctrl+Shift+X)) から、インストールされている MCP サーバーのリストを管理できます。
MCP サーバーを右クリックするか、ギア アイコンを選択して、次のアクションを実行します。
- 開始/停止/再起動: MCP サーバーを開始、停止、または再起動します。
- アカウントの切断: MCP サーバーとの認証用アカウントを切断します。
- 出力の表示: サーバーログを表示して問題を診断します。
- 構成の表示: MCP サーバーの構成を表示します。
- モデルアクセスの構成: MCP サーバーがアクセスできるモデル (サンプリング) を構成します。
- サンプリング要求の表示: MCP サーバーによって行われたサンプリング要求を表示します。
- リソースの参照: MCP サーバーによって提供されるリソースを表示します。
- アンインストール: 環境から MCP サーバーをアンインストールします。
または、コマンドパレットからMCP: サーバーを一覧表示コマンドを実行して、構成されている MCP サーバーのリストを表示します。その後、サーバーを選択してアクションを実行できます。
.vscode/mcp.json ファイルを開くと、VS Code はエディターから直接サーバーを開始、停止、または再起動するコマンドを表示します。
MCP URL ハンドラー
VS Code は、リンクから MCP サーバーをインストールするための URL ハンドラーを提供します。URL を作成するには、--add-mcp に提供するのと同じ形式で obj オブジェクトを構築し、次のロジックを使用してリンクを作成します。
// For Insiders, use `vscode-insiders` instead of `code`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;
このリンクはブラウザーで使用したり、Linux で xdg-open $LINK を介してコマンドラインで開いたりできます。
VS Code でサポートされている MCP 機能
VS Code は MCP サーバーに対して次の転送方法をサポートしています。
- 標準入出力 (
stdio): 標準入出力を介して通信するローカルプロセスとしてサーバーを実行します。 - ストリーミング可能な HTTP (
http): HTTP POST および GET を使用して (リモート) サーバーと通信します。 - サーバー送信イベント (
sse、レガシー): サーバー送信イベントを使用して HTTP 経由で (リモート) サーバーでサポートされます。
VS Code では以下の MCP 機能がサポートされています。
- ツール: エージェント モードで使用できる実行可能なアクション。
- プロンプト: オプションでパラメーターを持つ再利用可能なチャット プロンプト テンプレート。ユーザーはチャットでスラッシュ コマンド (
/mcp.servername.promptname) を介して呼び出すことができます。 - リソース: ユーザーがチャット コンテキストとして追加したり、VS Code で直接操作したりできるデータとコンテンツ。
- 認証: OAuth を使用して MCP サーバーへのアクセスを認証します。
- サンプリング（プレビュー）: ユーザーが構成したモデルとサブスクリプションを使用して言語モデルのリクエストを行います。
- エリシテーション: ユーザーからの入力を要求します。
- ワークスペースのルート: ユーザーのワークスペース構造に関する情報。
完全な仕様の詳細については、Model Context Protocol ドキュメントを参照してください。
ツール
ツールの定義
VS Code はエージェント モードで MCP ツールをサポートしており、タスクに基づいて必要に応じて呼び出されます。ユーザーはツール ピッカーでそれらを有効にして構成できます。ツール名とツールの説明は、ツール ピッカーおよびツールを実行する前に確認を求めるダイアログに表示されます。
ユーザーはツール確認ダイアログでモデル生成された入力パラメーターを編集できます。確認ダイアログは、readOnlyHint アノテーションが付けられていないすべてのツールに対して表示されます。
動的なツール検出
VS Code は動的なツール検出もサポートしており、サーバーがランタイム時にツールを登録できるようにします。たとえば、サーバーはワークスペースで検出されたフレームワークまたは言語に基づいて、あるいはユーザーのチャットプロンプトに応答して、異なるツールを提供できます。
ツールのアノテーション
ツールの動作に関する追加のメタデータを提供するには、ツールのアノテーションを使用できます。
title: ツールの人間が読めるタイトルで、ツールが呼び出されたときにチャット ビューに表示されます。readOnlyHint: ツールが読み取り専用であることを示すオプションのヒント。VS Code は読み取り専用ツールを実行するための確認を求めません。
リソース
リソースを使用すると、データとコンテンツを構造化された方法でユーザーに提供できます。ユーザーは VS Code でリソースに直接アクセスしたり、チャット プロンプトのコンテキストとして使用したりできます。たとえば、MCP サーバーはスクリーンショットを生成してリソースとして利用可能にしたり、リアルタイムで更新されるログ ファイルへのアクセスを提供したりできます。
MCP リソースを定義すると、リソース名が MCP Resources Quick Picks に表示されます。リソースは、MCP: リソースの参照コマンドで開くか、コンテキストの追加を選択してからMCP リソースを選択してチャット要求にアタッチできます。リソースはテキストまたはバイナリコンテンツを含めることができます。
VS Code はリソースの更新をサポートしており、ユーザーはエディターでリソースの内容への変更をリアルタイムで確認できます。
リソース テンプレート
VS Code はリソース テンプレートもサポートしており、ユーザーがリソースを参照する際に入力パラメーターを提供できるようにします。たとえば、データベース クエリ ツールはデータベース テーブル名を要求できます。
テンプレートを使用してリソースにアクセスすると、ユーザーはクイック ピックで必要なパラメーターの入力を求められます。パラメーターの値を示唆する補完を提供できます。
プロンプト
プロンプトは、ユーザーがスラッシュ コマンド (mcp.servername.promptname) を使用してチャットで呼び出すことができる再利用可能なチャット プロンプト テンプレートです。プロンプトは、さまざまなツールを強調表示したり、ユーザーのローカル コンテキストとサービスに適応する組み込みの複雑なワークフローを提供したりすることで、サーバーへのユーザーのオンボーディングに役立ちます。
プロンプト入力引数の値を提案するための補完を定義すると、VS Code はユーザーから入力を収集するためのダイアログを表示します。
server.prompt(
'teamGreeting',
'Generate a greeting for team members',
{
name: completable(z.string(), value => {
return ['Alice', 'Bob', 'Charlie'].filter(n => n.startsWith(value));
})
},
async ({ name }) => ({
messages: [
{
role: 'assistant',
content: { type: 'text', text: `Hello ${name}, welcome to the team!` }
}
]
})
);
ユーザーはプロンプト ダイアログでターミナル コマンドを入力し、そのコマンド出力をプロンプトの入力として使用できます。
プロンプト応答にリソース タイプを含めると、VS Code はそのリソースをチャット プロンプトのコンテキストとしてアタッチします。
認証
VS Code は認証を必要とする MCP サーバーをサポートしており、ユーザーは当該サービスに対する自分のユーザー アカウントに代わって動作する MCP サーバーと対話できます。
認証仕様は、MCP サーバーをリソース サーバーと認証サーバーから明確に分離しており、開発者は独自の OAuth 実装を一から構築するのではなく、既存の ID プロバイダーに認証を委任できます。
VS Code は GitHub と Microsoft Entra の組み込み認証サポートを備えています。MCP サーバーが最新の仕様を実装し、GitHub または Microsoft Entra を認証サーバーとして使用している場合、ユーザーはそのアカウントのアカウント メニュー > 信頼済み MCP サーバーの管理アクションを通じて、どの MCP サーバーが自分のアカウントにアクセスできるかを管理できます。
MCP サーバーが別の認証サーバーを使用している場合、VS Code は動的クライアント登録もサポートしています。ユーザーは、アカウント メニューからも認証ステータスを表示できます。動的クライアント登録を削除するには、コマンド パレットで認証: 動的認証プロバイダーを削除コマンドを使用できます。
VS Code は認証サーバーとして動作する MCP サーバーを依然としてサポートしていますが、新しいサーバーには最新の仕様を使用することをお勧めします。
サンプリング (プレビュー)
VS Code は MCP サーバーへのサンプリングアクセスを提供します。これにより、MCP サーバーはユーザーが構成したモデルとサブスクリプションを使用して言語モデルのリクエストを行うことができます。サンプリングは、大規模なデータを要約したり、クライアントに送信する前に情報を抽出したり、ツールロジックでよりスマートなエージェントの意思決定を実装したりするために使用できます。
MCP サーバーがサンプリング要求を初めて実行するときに、ユーザーはサーバーが自分のモデルにアクセスすることを承認するよう求められます。
ユーザーは、コマンド パレットでMCP: サーバーを一覧表示 > モデル アクセスを構成コマンドを使用して、MCP サーバーがサンプリングに使用できるモデルを指定できます。MCP サーバーで modelPreferences を指定して、サンプリングに使用するモデルに関するヒントを提供でき、VS Code はサーバーの設定を評価する際に許可されたモデルの中から選択します。
ユーザーは、コマンド パレットでMCP: サーバーを一覧表示 > サンプリング要求の表示コマンドを使用して、MCP サーバーが行ったサンプリング要求を表示できます。
ワークスペースのルート
VS Code は MCP サーバーにユーザーのワークスペース ルート フォルダー情報を提供します。
拡張機能に MCP サーバーを登録する
拡張機能で MCP サーバーを登録するには、次の手順を実行する必要があります。
- 拡張機能の
package.jsonファイルで MCP サーバー定義プロバイダーを定義します。 vscode.lm.registerMcpServerDefinitionProviderAPI を使用して、拡張機能コードで MCP サーバー定義プロバイダーを実装します。
VS Code 拡張機能で MCP サーバーを登録する方法の基本的な例から始めることができます。
1. package.json での静的構成
MCP サーバーを登録したい拡張機能は、プロバイダーの id を指定して package.json の contributes.mcpServerDefinitionProviders 拡張ポイントを提供する必要があります。この id は実装で使用されるものと一致する必要があります。
{
...
"contributes": {
"mcpServerDefinitionProviders": [
{
"id": "exampleProvider",
"label": "Example MCP Server Provider"
}
]
}
...
}
2. プロバイダーの実装
拡張機能で MCP サーバーを登録するには、vscode.lm.registerMcpServerDefinitionProvider API を使用してサーバーのMCP 構成を提供します。この API は providerId 文字列と McpServerDefinitionProvider オブジェクトを受け取ります。
McpServerDefinitionProvider オブジェクトには 3 つのプロパティがあります。
onDidChangeMcpServerDefinitions: MCP サーバー構成が変更されたときにトリガーされるイベント。provideMcpServerDefinitions: MCP サーバー構成の配列 (vscode.McpServerDefinition[]) を返す関数。resolveMcpServerDefinition: MCP サーバーの起動が必要なときにエディターが呼び出す関数。この関数を使用して、認証などのユーザー操作が必要な追加のアクションを実行します。
McpServerDefinition オブジェクトは次のいずれかのタイプです。
vscode.McpStdioServerDefinition: ローカル プロセスを実行し、その stdin および stdout ストリームで操作することで利用できる MCP サーバーを表します。vscode.McpHttpServerDefinition: ストリーミング可能な HTTP 転送を使用して利用できる MCP サーバーを表します。
MCP サーバー定義プロバイダーの例
次の例は、拡張機能に MCP サーバーを登録し、サーバーの起動時にユーザーに API キーを要求する方法を示しています。
import * as vscode from 'vscode';
export function activate(context: vscode.ExtensionContext) {
const didChangeEmitter = new vscode.EventEmitter<void>();
context.subscriptions.push(vscode.lm.registerMcpServerDefinitionProvider('exampleProvider', {
onDidChangeMcpServerDefinitions: didChangeEmitter.event,
provideMcpServerDefinitions: async () => {
let servers: vscode.McpServerDefinition[] = [];
// Example of a simple stdio server definition
servers.push(new vscode.McpStdioServerDefinition(
{
label: 'myServer',
command: 'node',
args: ['server.js'],
cwd: vscode.Uri.file('/path/to/server'),
env: {
API_KEY: ''
},
version: '1.0.0'
});
// Example of an HTTP server definition
servers.push(new vscode.McpHttpServerDefinition(
{
label: 'myRemoteServer',
uri: 'https://:3000',
headers: {
'API_VERSION': '1.0.0'
},
version: '1.0.0'
}));
return servers;
},
resolveMcpServerDefinition: async (server: vscode.McpServerDefinition) => {
if (server.label === 'myServer') {
// Get the API key from the user, e.g. using vscode.window.showInputBox
// Update the server definition with the API key
}
// Return undefined to indicate that the server should not be started or throw an error
// If there is a pending tool call, the editor will cancel it and return an error message
// to the language model.
return server;
}
}));
}
MCP サーバーのトラブルシューティングとデバッグ
VS Code の MCP 開発モード
MCP サーバーを開発する際には、VS Code で MCP 開発モードを有効にできます。開発モードを有効にするには、MCP サーバー構成に dev プロパティを追加し、次のプロパティを指定します。
watch: ファイルの変更を監視し、サーバーを自動的に再起動するためのグロブ パターン。debug: MCP サーバー プロセスを起動するときにアタッチするデバッガー (現在、nodeまたはpythonで起動されたサーバーのみがサポートされています)。
次の例は、src ディレクトリ内の TypeScript ファイルの変更を監視し、Node.js デバッガーを使用する Node.js MCP サーバーを構成する方法を示しています。
{
"servers": {
"my-mcp-server": {
"type": "stdio",
"command": "node",
"cwd": "${workspaceFolder}",
"args": ["./build/index.js"],
"dev": {
"watch": "src/**/*.ts",
"debug": { "type": "node" }
}
}
}
}
MCP 出力ログ
VS Code が MCP サーバーで問題に遭遇すると、チャット ビューにエラー インジケーターが表示されます。
チャット ビューのエラー通知を選択し、次に出力の表示オプションを選択してサーバー ログを表示します。または、コマンド パレットからMCP: サーバーを一覧表示を実行し、サーバーを選択してから出力の表示を選択します。
ベスト プラクティス
- 一意で説明的な名前を確実にするための命名規則
- 説明的なエラー メッセージを使用して、適切なエラー処理と検証を実装する
- 時間のかかる操作についてユーザーに通知するための進行状況レポートを使用する
- 複雑なやり取りを避けるために、ツール操作を集中させ、アトミックに保つ
- ユーザーがいつツールを使用するかを理解するのに役立つ説明とともに、ツールを明確に文書化する
- 既定値または明確なエラー メッセージを提供することにより、不足している入力パラメーターを適切に処理する
- VS Code でさまざまなコンテンツ タイプを適切に処理するために、リソースの MIME タイプを設定する
- リソースにアクセスするときにユーザーが入力パラメーターを提供できるように、リソース テンプレートを使用する
- パフォーマンスを向上させ、不要なネットワーク要求を減らすために、リソース コンテンツをキャッシュする
- 過剰なリソース使用を避けるために、サンプリング要求に適切なトークン制限を設定する
- サンプリング応答を使用する前に検証する
命名規則
MCP サーバーとそのコンポーネントには、以下の命名規則が推奨されます。
| コンポーネント | 命名規則のガイドライン |
|---|---|
| ツール名 |
|
| ツール入力パラメーター |
|
| リソース名 |
|
| リソース テンプレート パラメーター |
|
| プロンプト名 |
|
| プロンプト入力パラメーター |
|
MCP サーバーの作成を開始する
VS Code には、独自の MCP サーバーを開発するために必要なすべてのツールが揃っています。MCP サーバーは stdout を処理できる任意の言語で記述できますが、MCP の公式 SDK から始めるのが良いでしょう。
最初の MCP サーバーの構築を開始するのに、MCP for Beginners カリキュラムも役立つかもしれません。