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 サーバーを再利用できます。
以下のシナリオでは、言語モデル 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 ウェブサイトの 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 リソースのクイックピックに表示されます。リソースは、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 プロバイダー (IdP) に認証を委任できます。
VS Code には、GitHub および Microsoft Entra の組み込み認証サポートがあります。MCP サーバーが最新の仕様を実装し、GitHub または Microsoft Entra を認証サーバーとして使用している場合、ユーザーは、そのアカウントのアカウントメニュー > 信頼されている MCP サーバーを管理アクションを通じて、どのアカウントにどの MCP サーバーがアクセスできるかを管理できます。
VS Code は、GitHub および Microsoft Entra 以外の IdP に対する OAuth 2.1 標準および 2.0 標準を使用した承認をサポートしています。VS Code はまず動的クライアント登録 (DCR) ハンドシェイクを開始し、IdP が DCR をサポートしていない場合はクライアント資格情報ワークフローにフォールバックします。これにより、さまざまな IdP がそれぞれの MCP サーバーに対して静的なクライアント ID または特定のクライアント ID とシークレットのペアを作成するための柔軟性が高まります。
ユーザーは、アカウントメニューからも認証ステータスを表示できます。動的クライアント登録を削除するには、コマンドパレットで認証: 動的認証プロバイダーを削除コマンドを使用します。
MCP サーバーと VS Code の OAuth ワークフローが機能することを確認するためのチェックリストを以下に示します。
- MCP サーバーはMCP 承認仕様を定義しています。
- IdP は DCR またはクライアント資格情報のいずれかをサポートしている必要があります。
- リダイレクト URL リストには、次の URL を含める必要があります:
http://127.0.0.1:33418およびhttps://vscode.dev/redirect
DCR が MCP サーバーでサポートされていない場合、ユーザーはフォールバックのクライアント資格情報フローを経由します。
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 サーバーを登録したい拡張機能は、package.json の contributes.mcpServerDefinitionProviders 拡張ポイントをプロバイダーの id とともに提供する必要があります。この 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: ローカルプロセスを実行し、その標準入力および標準出力ストリームで動作することによって利用できる 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 カリキュラムも役立つかもしれません。