編輯

MCP 開發者指南

Name: Visual Studio Code
Author: Microsoft

模型上下文協議 (MCP) 是一項開放標準，使 AI 模型能夠透過統一介面與外部工具和服務進行互動。Visual Studio Code 實現了完整的 MCP 規範，使您能夠建立 MCP 伺服器，為在 VS Code 中擴充套件 AI 代理功能提供工具、提示和資源。

本指南涵蓋了構建與 VS Code 和其他 MCP 客戶端無縫協作的 MCP 伺服器所需瞭解的一切。

重要

VS Code 中的 MCP 支援目前處於預覽階段。

為什麼使用 MCP 伺服器？

實現 MCP 伺服器以透過語言模型工具擴充套件 VS Code 中的聊天功能具有以下優勢：

透過專用、特定領域的工具擴充套件代理模式，這些工具會在響應使用者提示時自動呼叫。例如，啟用資料庫腳手架和查詢以動態向 LLM 提供相關上下文。
適用於本地和遠端場景的靈活部署選項。
在不同工具和平臺之間重用您的 MCP 伺服器。

在以下情況下，您可能需要考慮使用語言模型 API 實現語言模型工具：

您希望透過使用擴充套件 API 與 VS Code 深度整合。
您希望透過 Visual Studio Marketplace 分發您的工具和更新。

將 MCP 伺服器新增到 VS Code

使用者可以透過多種方式在 VS Code 中新增 MCP 伺服器：

工作區配置：在工作區中的 .vscode/mcp.json 檔案中指定伺服器配置。
全域性配置：在使用者配置檔案中全域性定義伺服器。
自動發現：VS Code 可以從 Claude Desktop 等其他工具中發現伺服器。
擴充套件：VS Code 擴充套件可以程式設計方式註冊 MCP 伺服器。

此外，使用者可以透過開啟特殊 URL (vscode:mcp/install) 觸發 MCP 安裝，該 URL 用於 VS Code 網站上的 MCP 相簿。使用者可以直接從擴充套件檢視中的 MCP 檢視訪問相簿。

最後，使用 --add-mcp 命令列選項從命令列安裝 MCP 伺服器。

管理 MCP 伺服器

您可以在 VS Code 的擴充套件檢視（⇧⌘X (Windows、Linux Ctrl+Shift+X)）中管理已安裝的 MCP 伺服器列表。

Screenshot showing the MCP servers in the Extensions view.

右鍵單擊 MCP 伺服器或選擇齒輪圖示以執行以下操作：

啟動/停止/重新啟動：啟動、停止或重新啟動 MCP 伺服器。
斷開賬戶：斷開用於 MCP 伺服器認證的賬戶。
顯示輸出：檢視伺服器日誌以診斷問題。
顯示配置：檢視 MCP 伺服器配置。
配置模型訪問：配置 MCP 伺服器可以訪問哪些模型（取樣）。
顯示取樣請求：檢視 MCP 伺服器發出的取樣請求。
瀏覽資源：檢視 MCP 伺服器提供的資源。
解除安裝：從您的環境中解除安裝 MCP 伺服器。

或者，從命令面板執行 MCP: 列出伺服器 命令以檢視已配置的 MCP 伺服器列表。然後，您可以選擇一個伺服器並對其執行操作。

提示

當您開啟 .vscode/mcp.json 檔案時，VS Code 會直接從編輯器中顯示啟動、停止或重新啟動伺服器的命令。

MCP server configuration with lenses to manage server.

MCP URL 處理程式

VS Code 提供了一個 URL 處理程式，用於從連結安裝 MCP 伺服器。要形成 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 伺服器。
取樣 （預覽）：使用使用者配置的模型和訂閱發出語言模型請求。
啟發：請求使用者輸入。
工作區根：有關使用者工作區結構的資訊。

有關完整的規範詳細資訊，請參閱模型上下文協議文件。

工具

工具定義

VS Code 支援代理模式下的 MCP 工具，它們會根據任務需要進行呼叫。使用者可以使用工具選擇器啟用和配置它們。工具描述會與工具名稱一起顯示在工具選擇器中，並在執行工具前請求確認的對話方塊中顯示。

Screenshot that shows the tools picker in agent mode, highlighting tools from an MCP server.

使用者可以在工具確認對話方塊中編輯模型生成的輸入引數。對於所有未標記 readOnlyHint 註釋的工具，都會顯示確認對話方塊。

Screenshot that shows the tool confirmation dialog with input parameters for an MCP tool.

動態工具發現

VS Code 還支援動態工具發現，允許伺服器在執行時註冊工具。例如，伺服器可以根據工作區中檢測到的框架或語言，或響應使用者的聊天提示，提供不同的工具。

工具註釋

要提供有關工具行為的額外元資料，可以使用工具註釋：

title：工具的人類可讀標題，在呼叫工具時顯示在聊天檢視中。
readOnlyHint：可選提示，指示工具是隻讀的。VS Code 不會要求確認執行只讀工具。

資源

資源使您能夠以結構化方式向用戶提供資料和內容。使用者可以直接在 VS Code 中訪問資源，或將其用作聊天提示中的上下文。例如，MCP 伺服器可以生成螢幕截圖並將其作為資源提供，或者提供對日誌檔案的訪問，然後即時更新這些日誌檔案。

當您定義 MCP 資源時，資源名稱會顯示在 MCP 資源快速選擇中。資源可以透過 MCP: 瀏覽資源 命令開啟，或透過 新增上下文 並選擇 MCP 資源 附加到聊天請求。資源可以包含文字或二進位制內容。

Screenshot that shows the MCP Resources Quick Pick.

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!` }
      }
    ]
  })
);

Screenshot that shows the prompt dialog for an MCP prompt with input parameters.

注意

使用者可以在提示對話方塊中輸入終端命令，並使用命令輸出作為提示的輸入。

當您在提示響應中包含資源型別時，VS Code 會將該資源作為上下文附加到聊天提示。

授權

VS Code 支援需要身份驗證的 MCP 伺服器，允許使用者與代表其使用者賬戶在該服務上執行的 MCP 伺服器進行互動。

授權規範將 MCP 伺服器（作為資源伺服器）與授權伺服器乾淨地分離，允許開發人員將身份驗證委託給現有的身份提供商 (IdP)，而不是從頭開始構建自己的 OAuth 實現。

VS Code 內建了對 GitHub 和 Microsoft Entra 的身份驗證支援。如果您的 MCP 伺服器實現最新規範並使用 GitHub 或 Microsoft Entra 作為授權伺服器，使用者可以透過 賬戶選單 > 管理受信任的 MCP 伺服器 操作來管理哪些 MCP 伺服器可以訪問其賬戶。

Screenshot that shows the Accounts menu with the Manage Trusted MCP Servers action.

VS Code 支援使用 OAuth 2.1 標準和 2.0 標準對 GitHub 和 Microsoft Entra 以外的其他 IdP 進行授權。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。

當 MCP 伺服器不支援 DCR 時，使用者將透過回退客戶端憑據流程。

Screenshot that shows the authorization when DCR is not supported for a MCP server.

Screenshot that shows the authorization when Client ID for a MCP server is requested.

Screenshot that shows the authorization when Client Secret for a MCP server is requested.

注意

VS Code 仍然支援充當授權伺服器的 MCP 伺服器，但建議新伺服器使用最新規範。

取樣（預覽）

VS Code 為 MCP 伺服器提供了取樣訪問。這允許您的 MCP 伺服器使用使用者配置的模型和訂閱發出語言模型請求。取樣可用於在將資料傳送到客戶端之前總結大量資料或提取資訊，或在工具邏輯中實現更智慧的代理決策。

MCP 伺服器第一次執行取樣請求時，系統會提示使用者授權伺服器訪問其模型。

Screenshot that shows the authorization prompt for an MCP server to access models.

使用者可以透過命令面板中的 MCP: 列出伺服器 > 配置模型訪問 命令來指定允許 MCP 伺服器用於取樣的模型。您可以在 MCP 伺服器中指定 modelPreferences 以提供有關要用於取樣的模型的提示，VS Code 將在評估伺服器偏好時從允許的模型中進行選擇。

Screenshot that shows the Configure Model Access dialog for an MCP server.

使用者可以使用命令面板中的 MCP: 列出伺服器 > 顯示取樣請求 命令檢視 MCP 伺服器發出的取樣請求。

工作區根目錄

VS Code 向 MCP 伺服器提供使用者的工作區根資料夾資訊。

在擴充套件中註冊 MCP 伺服器

要在擴充套件中註冊 MCP 伺服器，您需要執行以下步驟：

在擴充套件的 package.json 檔案中定義 MCP 伺服器定義提供程式。
使用 vscode.lm.registerMcpServerDefinitionProvider API 在擴充套件程式碼中實現 MCP 伺服器定義提供程式。

您可以從一個基本的如何在 VS Code 擴充套件中註冊 MCP 伺服器的示例開始。

1. `package.json` 中的靜態配置

希望註冊 MCP 伺服器的擴充套件必須在 package.json 中貢獻 contributes.mcpServerDefinitionProviders 擴充套件點，並提供提供程式的 id。此 id 應與實現中使用的 id 匹配。

{
    ...
    "contributes": {
        "mcpServerDefinitionProviders": [
            {
                "id": "exampleProvider",
                "label": "Example MCP Server Provider"
            }
        ]
    }
    ...
}

2. 實現提供程式

要在擴充套件中註冊 MCP 伺服器，請使用 vscode.lm.registerMcpServerDefinitionProvider API 提供伺服器的 MCP 配置。該 API 接受一個 providerId 字串和一個 McpServerDefinitionProvider 物件。

McpServerDefinitionProvider 物件具有三個屬性：

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 開發模式。要啟用開發模式，請將 dev 屬性新增到您的 MCP 伺服器配置中，並指定以下屬性：

watch：一個 glob 模式，用於監視檔案更改並自動重新啟動伺服器。
debug：啟動 MCP 伺服器程序時附加的偵錯程式（目前僅支援使用 node 或 python 啟動的伺服器）。

以下示例演示瞭如何配置一個 Node.js MCP 伺服器，該伺服器監視 src 目錄中 TypeScript 檔案的更改並使用 Node.js 偵錯程式：

{
  "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: 列出伺服器，選擇伺服器，然後選擇 顯示輸出。

MCP Server Error Output

最佳實踐

命名約定以確保唯一且具有描述性的名稱。
實現適當的錯誤處理和驗證，並附帶描述性錯誤訊息。
使用進度報告通知使用者長時間執行的操作。
保持工具操作集中和原子化，以避免複雜的互動。
清晰地記錄您的工具，並提供描述，幫助使用者瞭解何時使用它們。
優雅地處理缺失的輸入引數，提供預設值或清晰的錯誤訊息。
為資源設定 MIME 型別，以確保在 VS Code 中正確處理不同內容型別。
使用資源模板允許使用者在訪問資源時提供輸入引數。
快取資源內容以提高效能並減少不必要的網路請求。
為取樣請求設定合理的令牌限制，以避免過多的資源使用。
在使用取樣響應之前驗證取樣響應。

命名約定

建議對 MCP 伺服器及其元件採用以下命名約定：

元件	命名約定指南
工具名稱	在 MCP 伺服器中是唯一的。描述操作及其目標。使用蛇形命名法，結構為 `{verb}_{noun}`。示例：`generate_report`、`fetch_data`、`analyze_code`
工具輸入引數	描述引數的目的。對於多詞引數使用駝峰命名法。示例：`path`、`queryString`、`userId`
資源名稱	在 MCP 伺服器中是唯一的。描述資源的內容。使用標題大小寫。示例：`Application Logs`、`Database Table`、`GitHub Repository`
資源模板引數	描述引數的目的。對於多詞引數使用駝峰命名法。示例：`name`、`repo`、`fileType`
提示名稱	在 MCP 伺服器中是唯一的。描述提示的預期用途。對於多詞引數使用駝峰命名法。示例：`generateApiRoute`、`performSecurityReview`、`analyzeCodeQuality`
提示輸入引數	描述引數的目的。對於多詞引數使用駝峰命名法。示例：`filePath`、`queryString`、`userId`

開始建立 MCP 伺服器

VS Code 擁有開發自己的 MCP 伺服器所需的所有工具。雖然 MCP 伺服器可以用任何能夠處理 stdout 的語言編寫，但 MCP 的官方 SDK 是一個很好的起點：

您可能還會發現 MCP 初學者課程對您開始構建第一個 MCP 伺服器有所幫助。

09/11/2025