MCP 開発者ガイド

Model Context Protocol (MCP) は、AI モデルが統一されたインターフェースを介して外部ツールやサービスと対話できるようにするオープン標準です。Visual Studio Code は MCP 仕様を完全に実装しており、ツール、プロンプト、リソースを提供する MCP サーバーを作成して、VS Code 内の AI エージェントの機能を拡張できます。

MCP サーバーは、組み込みツールや拡張機能が提供するツールと並んで、VS Code で利用可能な 3 種類のツールの 1 つを提供します。ツールタイプの詳細をご覧ください。

このガイドでは、VS Code やその他の MCP クライアントとシームレスに連携する MCP サーバーを構築するために必要なすべての情報を網羅しています。

なぜ MCP サーバーを使用するのか？

言語モデルツールを使用して VS Code のチャットを拡張するために MCP サーバーを実装することには、次のような利点があります。

• エージェントモードの拡張: ユーザーのプロンプトに応答する過程で自動的に呼び出される、専門的でドメイン固有のツールを使用できます。例えば、データベースのスキャフォールディングやクエリ機能を有効にすることで、LLM に関連するコンテキストを動的に提供できます。
• 柔軟なデプロイオプション: ローカルおよびリモートのシナリオに対応します。
• 再利用性: さまざまなツールやプラットフォーム間で MCP サーバーを再利用できます。

次のようなシナリオでは、Language Model API を使用した言語モデルツールの実装を検討してください。

• 拡張機能 API を使用して VS Code と深く統合したい場合。
• Visual Studio Marketplace を使用してツールやアップデートを配布したい場合。

VS Code がサポートする MCP 機能

VS Code は以下の MCP 機能をサポートしています。

• トランスポート:

  • ローカル標準入出力 (stdio)
  • ストリーミング可能な HTTP (http)
  • Server-sent events (sse) - レガシーサポート。

• 機能:

  • ツール: 追加のツールでエージェントモードを拡張する
  • プロンプト: チャット内のスラッシュコマンドとして再利用可能なプロンプトを追加する
  • リソース: ユーザーがチャットのコンテキストに追加したり、直接操作したりできるデータやコンテンツを提供する
  • 要求 (Elicitation): ユーザーからの入力を要求する
  • サンプリング: ユーザーが設定したモデルとサブスクリプションを使用して言語モデルのリクエストを行う
  • 認証: OAuth を使用して MCP サーバーへのアクセスを認可する
  • サーバー指示
  • ルート (Roots): ユーザーのワークスペースルートフォルダーに関する情報を提供する
  • MCP Apps: ツールからインタラクティブな UI コンポーネントを返す

ツール

ツール定義

VS Code はエージェントモードで MCP ツールをサポートしており、タスクに基づいて必要に応じて呼び出されます。ユーザーはツールピッカーで有効化・設定できます。ツールの説明は、ツール名と並んでツールピッカーに表示され、ツールを実行する前の確認ダイアログにも表示されます。

ユーザーは、ツール確認ダイアログでモデルが生成した入力パラメーターを編集できます。確認ダイアログは、readOnlyHint アノテーションが付与されていないすべてのツールに対して表示されます。

動的ツール検出

VS Code は動的ツール検出もサポートしており、サーバーが実行時にツールを登録できるようにしています。例えば、サーバーはワークスペースで検出されたフレームワークや言語に基づいて、またはユーザーのチャットプロンプトに応じて、異なるツールを提供できます。

ツールアノテーション

ツールの動作に関する追加メタデータを提供するには、ツールアノテーションを使用できます。

• title: ツールが呼び出されたときにチャットビューに表示される、人間が読み取れるツール名。
• readOnlyHint: ツールが読み取り専用であることを示すオプションのヒント。VS Code は読み取り専用ツールの実行には確認を求めません。

リソース

リソースを使用すると、構造化された方法でユーザーにデータやコンテンツを提供できます。ユーザーは VS Code 内でリソースに直接アクセスしたり、チャットプロンプトのコンテキストとして使用したりできます。例えば、MCP サーバーがスクリーンショットを生成してリソースとして利用可能にしたり、リアルタイムで更新されるログファイルへのアクセスを提供したりできます。

MCP リソースを定義すると、リソース名が「MCP Resources」クイックピックに表示されます。リソースは **MCP: Browse Resources** コマンドで開くか、**Add Context** を選択して **MCP Resource** を選択することでチャットリクエストに添付できます。リソースにはテキストまたはバイナリコンテンツを含めることができます。

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 はそのリソースをチャットプロンプトのコンテキストとして添付します。

認可 (Authorization)

VS Code は認証が必要な MCP サーバーをサポートしており、ユーザーはそのサービスのアカウントに代わって動作する MCP サーバーと対話できます。

認可仕様は、MCP サーバーをリソースサーバーとして、また認可サーバーとして明確に分離しており、開発者は独自の OAuth 実装を一から構築するのではなく、既存のアイデンティティプロバイダー (IdP) に認証を委任できます。

VS Code は GitHub と Microsoft Entra の認証を組み込みでサポートしています。あなたの MCP サーバーが最新の仕様を実装しており、GitHub または Microsoft Entra を認可サーバーとして使用している場合、ユーザーは **Accounts メニュー** > **Manage Trusted MCP Servers** アクションを通じて、どのアカウントでどの MCP サーバーにアクセス許可を与えるかを管理できます。

VS Code は、GitHub および Microsoft Entra 以外の IdP に対して OAuth 2.1 および 2.0 標準を使用した認可をサポートしています。VS Code はまず 動的クライアント登録 (DCR) ハンドシェイクから開始し、IdP が DCR をサポートしていない場合はクライアント認証ワークフローにフォールバックします。これにより、各 MCP サーバーに対して静的なクライアント ID や特定のクライアント ID/シークレットペアを作成する際に、さまざまな IdP に柔軟に対応できます。

ユーザーは **Accounts メニュー** を通じて認証ステータスを確認することもできます。動的なクライアント登録を削除するには、コマンドパレットで **Authentication: Remove Dynamic Authentication Providers** コマンドを使用できます。

以下は、MCP サーバーと VS Code の OAuth ワークフローが正しく動作するためのチェックリストです。

1. MCP サーバーが MCP 認可仕様 を定義していること。
2. IdP が DCR またはクライアント認証情報のいずれかをサポートしていること。
3. リダイレクト URL リストに http://127.0.0.1:33418 と https://vscode.dev/redirect が含まれていること。

MCP サーバーが DCR をサポートしていない場合、ユーザーはフォールバックのクライアント認証ワークフローを経由します。

サンプリング

VS Code は MCP サーバー向けに サンプリング へのアクセスを提供します。これにより、MCP サーバーはユーザーが設定したモデルとサブスクリプションを使用して言語モデルのリクエストを行うことができます。例えば、サンプリングを使用して大規模なデータセットを要約したり、クライアントに送信する前に情報を抽出したり、ツール内でエージェント的な意思決定ロジックを実装したりできます。

MCP サーバーが初めてサンプリングリクエストを実行する際、ユーザーはサーバーにモデルへのアクセスを許可するよう求められます。

特定のモデルでサンプリングリクエストを行う場合、ユーザーはコマンドパレットの **MCP: List Servers** > **Configure Model Access** コマンドで、MCP サーバーがどのモデルを使用できるかを制限できることに留意してください。MCP サーバーで modelPreferences を指定してサンプリングに使用するモデルのヒントを提供すると、VS Code は許可されたモデルの中から選択します。

ユーザーは、コマンドパレットの **MCP: List Servers** > **Show Sampling Requests** コマンドで、MCP サーバーが行ったサンプリングリクエストを確認できます。

ワークスペースルート

VS Code はユーザーのワークスペースルートフォルダー情報を MCP サーバーに提供します。

MCP Apps

MCP Apps を使用すると、ツールがテキストのみの出力ではなく、チャット内にインラインでレンダリングされるインタラクティブな UI コンポーネントを返すことができます。これは、ドラッグ＆ドロップによるリストの並べ替え、可視化、フォーム、多段階ワークフローなどのシナリオで役立ちます。

アーキテクチャ

MCP Apps は「ツール + UI リソース」パターンを使用します。

1. _meta.ui.resourceUri が UI リソースを指すツールを定義する。
2. ui:// URI スキームと MIME タイプ text/html;profile=mcp-app を持つ UI リソースを作成する。
3. HTML リソースはサンドボックス化された iframe 内で実行され、MCP Apps SDK を使用して VS Code と通信する。

SDK

@modelcontextprotocol/ext-apps パッケージを使用して MCP Apps を構築します。SDK が提供するもの：

• App クラス: ホストと通信するためのメインインターフェース。

  • connect(): VS Code との接続を確立する。
  • callServerTool(name, args): 元の MCP サーバー上のツールを呼び出す。
  • sendMessage(content): チャット入力にメッセージを送信する。
  • updateModelContext(context): 今後の会話のターンのためにコンテキストを提供する。
  • openLink(url): ブラウザーで URL を開くよう要求する。
  • sendLog(level, message): デバッグログを送信する（会話には追加されない）。

• 通知ハンドラー: VS Code からイベントを受信するためにこれらを設定します。

  • ontoolinput: 完全なツール引数を受信する。
  • ontoolinputpartial: ストリーミング中の部分引数を受信する。
  • ontoolresult: ツール実行結果を受信する。
  • ontoolcancelled: ツールキャンセルを処理する。
  • onhostcontextchanged: テーマやロケールの変更に応答する。
  • onteardown: アンマウント前にクリーンアップする。

VS Code の動作と制限事項

セキュリティ

MCP Apps は、コンテンツセキュリティポリシー (CSP) が適用されたサンドボックス化 iframe 内で実行されます。UI リソースを定義する際、アプリがアクセスする必要のあるドメインを宣言してください。

• connectDomains: fetch/XHR リクエスト用のドメイン。
• resourceDomains: 画像、フォント、その他のリソース用のドメイン。
• frameDomains: iframe に埋め込み可能なドメイン。

詳細情報

• MCP Apps 仕様
• MCP アプリ SDK とサンプル
• MCP Apps 発表ブログ記事

アイコン

VS Code は、MCP サーバー、リソース、およびツールに提供される icons をサポートしています。MCP アイコンには、画像の URI である src プロパティがあります。

• HTTP または SSE トランスポートを使用する MCP サーバーは、MCP サーバーがホストされているのと同じ権限元から画像を提供できます。例えば、https://example.com/mcp で設定されたサーバーは example.com から画像を提供できます。
• stdio トランスポートを使用する MCP サーバーは、file:/// URI を使用してファイルシステムから画像を提供できます。
• すべての MCP サーバーは、data: で始まるデータ URI として画像を埋め込むことができます。

VS Code に MCP サーバーを追加する

ユーザーはいくつかの方法で VS Code 内に MCP サーバーを追加できます。

• Web から直接インストール: ウェブサイト上の特別な MCP インストール URL (vscode:mcp/install) を使用。
• ワークスペース設定: ワークスペース内の .vscode/mcp.json ファイルでサーバー設定を指定。
• グローバル設定: ユーザーのプロファイル内でグローバルにサーバーを定義。
• 自動検出: VS Code は Claude Desktop などの他のツールからサーバーを検出可能。
• 拡張機能: VS Code 拡張機能がプログラムで MCP サーバーを登録可能。
• コマンドライン: --add-mcp VS Code コマンドラインオプションを使用してコマンドラインから MCP サーバーをインストール。

VS Code に MCP サーバーを追加するさまざまな方法の詳細をご覧ください。

MCP サーバーの管理

VS Code の拡張機能ビュー (⇧⌘X (Windows, Linux Ctrl+Shift+X)) から、インストールされている MCP サーバーのリストを管理できます。

MCP サーバーを右クリックするか、歯車アイコンを選択して、サーバーに対するさまざまな管理アクションを実行します。あるいは、コマンドパレットから **MCP: List Servers** コマンドを実行して、設定された MCP サーバーのリストを表示します。そこからサーバーを選択してアクションを実行できます。

MCP インストール URL を作成する

VS Code はリンクから MCP サーバーをインストールするための URL ハンドラーを提供しています: vscode:mcp/install?{json-configuration} (Insiders 版: vscode-insiders:mcp/install?{json-configuration})。

JSON サーバー設定を {\"name\":\"server-name\",\"command\":...} の形式で提供し、JSON 文字列化と URL エンコードを行います。例えば、以下のロジックを使用してインストール URL を作成します。

// For Insiders, use `vscode-insiders` instead of `code`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;

このリンクはブラウザーで使用するか、コマンドライン（Linux の場合は xdg-open $LINK など）から開くことができます。

拡張機能に MCP サーバーを登録する

拡張機能に MCP サーバーを登録するには、以下の手順を実行する必要があります。

1. 拡張機能の package.json ファイルで MCP サーバー定義プロバイダーを定義する。
2. vscode.lm.registerMcpServerDefinitionProvider API を使用して、拡張機能コード内に 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: ローカルプロセスを実行し、その stdin/stdout ストリームで動作する MCP サーバーを表します。
• vscode.McpHttpServerDefinition: ストリーミング可能な HTTP トランスポートを使用して利用可能な MCP サーバーを表します。

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 サーバーを開発する際は、MCP サーバー設定に dev キーを追加することで 開発モード を有効にできます。これは 2 つのプロパティを持つオブジェクトです。

• watch: ファイルの変更を監視して MCP サーバーを再起動するための glob パターン、または glob パターンの配列。

• debug: MCP サーバーでデバッガーをセットアップできます。現在、VS Code は Node.js および Python の MCP サーバーのデバッグをサポートしています。

  Node.js MCP サーバー

  Node.js MCP サーバーをデバッグするには、debug.type プロパティを node に設定します。

  {
    "servers": {
      "my-mcp-server": {
        "type": "stdio",
        "command": "node",
        "cwd": "${workspaceFolder}",
        "args": ["./build/index.js"],
        "dev": {
          "watch": "src/**/*.ts",
          "debug": { "type": "node" }
        }
      }
    }
  }
  

  Python MCP サーバー

  Python MCP サーバーをデバッグするには、debug.type プロパティを debugpy に設定し、オプションでデフォルトの Python 環境にインストールされていない場合は debug.debugpyPath プロパティを debugpy モジュールのパスに設定します。

  {
    "servers": {
      "my-python-mcp-server": {
        "type": "stdio",
        "command": "python",
        "cwd": "${workspaceFolder}",
        "args": ["./server.py"],
        "dev": {
          "watch": "**/*.py",
          "debug": {
            "type": "debugpy",
            "debugpyPath": "/path/to/debugpy"
          }
        }
      }
    }
  }
  

MCP 出力ログ

VS Code が MCP サーバーで問題に遭遇した場合、チャットビューにエラーインジケーターを表示します。

チャットビューのエラー通知を選択し、**Show Output** オプションを選択してサーバーログを表示します。あるいは、コマンドパレットから **MCP: List Servers** を実行し、サーバーを選択して **Show Output** を選択します。

ベストプラクティス

• 命名規則: 一貫性があり説明的な名前を付ける。
• 適切なエラー処理とバリデーションの実装: 分かりやすいエラーメッセージを提供する。
• 進捗報告の使用: 時間のかかる操作についてユーザーに通知する。
• ツール操作の集中と原子化: 複雑な対話を避ける。
• ツールの明確なドキュメント化: いつ使用すべきかをユーザーが理解できる説明を記載する。
• 入力パラメーター不足への適切な対応: デフォルト値や明確なエラーメッセージを提供する。
• リソースの MIME タイプ設定: VS Code 内での適切なコンテンツタイプ処理を保証する。
• リソーステンプレートの使用: リソースアクセス時に入力パラメーターを提供できるようにする。
• リソースコンテンツのキャッシュ: パフォーマンスを向上させ、不必要なネットワークリクエストを減らす。
• サンプリングリクエストへの適切なトークン制限の設定: 過度なリソース消費を防ぐ。
• サンプリング応答のバリデーション: 使用前に応答を確認する。

命名規則

MCP サーバーとそのコンポーネントには、以下の命名規則が推奨されます。

MCP サーバーの作成を始める

VS Code には、独自の MCP サーバーを開発するために必要なすべてのツールが揃っています。MCP サーバーは stdout を処理できるあらゆる言語で記述できますが、MCP の公式 SDK は手始めとして最適です。

• TypeScript SDK
• Python SDK
• Java SDK
• Kotlin SDK
• C# SDK

最初の MCP サーバー構築を始めるには、MCP for Beginners カリキュラム も役立つでしょう。

関連記事

• 言語モデルツールを提供する
• エージェントモードで MCP ツールを使用する
• VS Code がキュレーションする MCP サーバーリスト
• Model Context Protocol ドキュメント