現已釋出！閱讀關於 11 月新增功能和修復的內容。

MCP 開發者指南

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

MCP 伺服器提供 VS Code 中三種可用工具的一種，另外兩種是內建工具和擴充套件貢獻的工具。詳細瞭解 工具型別。

本指南涵蓋了您需要了解的全部內容，以便構建能夠與 VS Code 和其他 MCP 客戶端無縫協同工作的 MCP 伺服器。

提示

有關將 MCP 伺服器作為終端使用者使用的資訊，請參閱 在 VS Code 中使用 MCP 伺服器。

為什麼使用 MCP 伺服器？

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

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

在以下場景中，您可能會考慮使用 語言模型 API 來實現語言模型工具：

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

VS Code 支援的 MCP 功能

VS Code 支援以下 MCP 功能：

  • 傳輸:

    • 本地標準輸入/輸出 (stdio)
    • 流式 HTTP (http)
    • 伺服器傳送事件 (sse) - 舊版支援。

  • 功能:

    • 工具：透過額外的工具擴充套件 代理模式。
    • 提示：將可重用的提示新增為聊天中的斜槓命令。
    • 資源：提供使用者可以新增為聊天上下文或直接在 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 伺服器可以生成螢幕截圖並將其作為資源提供，或者提供對日誌檔案的訪問，然後這些檔案會在 VS Code 中即時更新。

當您定義 MCP 資源時，資源名稱會顯示在 MCP 資源快速選擇中。可以透過 MCP: Browse Resources 命令開啟資源，或者透過 Add Context 並選擇 MCP Resource 將其附加到聊天請求中。資源可以包含文字或二進位制內容。

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 作為授權伺服器，使用者可以透過其賬戶的“Accounts menu”>“Manage Trusted MCP Servers”操作來管理哪些 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-金鑰對。

然後，使用者可以透過“Accounts menu”檢視其身份驗證狀態。要刪除動態客戶端註冊，使用者可以使用命令面板中的“Authentication: Remove Dynamic Authentication Providers”命令。

以下是確保您的 MCP 伺服器和 VS Code 的 OAuth 工作流能夠正常工作的清單：

  1. MCP 伺服器定義了 MCP 授權規範。
  2. IdP 必須支援 DCR 或客戶端憑據。
  3. 重定向 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: List Servers”>“Configure Model Access”命令來限制 MCP 伺服器可以使用哪些模型。當您在 MCP 伺服器中指定 modelPreferences 以提供關於取樣模型選擇的提示時，VS Code 將從允許的模型中進行選擇。

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

使用者可以透過命令面板中的“MCP: List Servers”>“Show Sampling Requests”命令檢視 MCP 伺服器發起的取樣請求。

工作區根目錄

VS Code 會將使用者的當前工作區根資料夾資訊提供給 MCP 伺服器。

圖示

VS Code 支援 MCP 伺服器、資源和工具上提供的 icons。MCP 圖示具有 src 屬性，該屬性是影像的 URI。

  • 使用 HTTP 或 SSE 傳輸的 MCP 伺服器可以從 MCP 伺服器託管的同一權威機構提供影像。例如，配置為 https://example.com/mcp 的伺服器可以從 example.com 提供影像。
  • 使用 stdio 傳輸的 MCP 伺服器可以使用 file:/// URI 從檔案系統提供影像。
  • 任何 MCP 伺服器都可以嵌入以 data: 開頭的資料 URI 影像。

將 MCP 伺服器新增到 VS Code

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

  • 直接從 Web 安裝：在您的網站上使用特殊的 MCP 安裝 URL（vscode:mcp/install）。
  • 工作區配置：在工作區的 .vscode/mcp.json 檔案中指定伺服器配置。
  • 全域性配置：在使用者 配置檔案 中全域性定義伺服器。
  • 自動發現：VS Code 可以從 Claude Desktop 等其他工具發現伺服器。
  • 擴充套件：VS Code 擴充套件可以透過程式設計方式註冊 MCP 伺服器。
  • 命令列：使用 --add-mcp VS Code 命令列選項從命令列安裝 MCP 伺服器。

詳細瞭解 將 MCP 伺服器新增到 VS Code 的不同方法。

管理 MCP 伺服器

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

Screenshot showing the MCP servers in the Extensions view.

右鍵單擊 MCP 伺服器或選擇齒輪圖示，即可對伺服器執行不同的管理操作。或者，從命令面板執行 MCP: List Servers 命令以檢視已配置 MCP 伺服器的列表。然後，您可以選擇一個伺服器並對其執行操作。

提示

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

MCP server configuration with lenses to manage server.

建立 MCP 安裝 URL

VS Code 提供了一個 URL 處理程式，用於從連結安裝 MCP 伺服器：vscode:mcp/install?{json-configuration} (Insiders: vscode-insiders:mcp/install?{json-configuration})。

以 {\"name\":\"server-name\",\"command\":...} 的形式提供 JSON 伺服器配置，然後對其進行 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 伺服器定義提供程式。

您可以從 如何將 MCP 伺服器註冊到 VS Code 擴充套件的示例 入手。

1. package.json 中的靜態配置

要註冊 MCP 伺服器的擴充套件必須在 package.json 中使用提供程式的 id 來貢獻 contributes.mcpServerDefinitionProviders 擴充套件點。此 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：表示透過執行本地程序並在其 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 伺服器時，可以透過向 MCP 伺服器配置新增 dev 鍵來啟用 MCP 伺服器的開發模式。這是一個包含兩個屬性的物件：

  • watch：一個檔案 glob 模式，用於監視檔案更改以重新啟動 MCP 伺服器。

  • 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，並可以選擇將 debug.debugpyPath 屬性設定為 debugpy 模組的路徑（如果它未安裝在預設 Python 環境中）。

    {
  "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 伺服器問題時，會在聊天檢視中顯示一個錯誤指示器。

MCP Server Error

選擇聊天檢視中的錯誤通知，然後選擇“Show Output”選項以檢視伺服器日誌。或者，從命令面板執行 MCP: List Servers，選擇伺服器，然後選擇“Show Output”。

MCP Server Error Output

最佳實踐

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

命名約定

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

元件 命名約定指南
工具名稱
  • 在 MCP 伺服器內部唯一
  • 描述操作和操作的目標
  • 使用 snake_case，結構為 {verb}_{noun}
  • 示例：generate_report、fetch_data、analyze_code
工具輸入引數
  • 描述引數的用途
  • 多詞引數使用 camelCase
  • 示例：path、queryString、userId
資源名稱
  • 在 MCP 伺服器內部唯一
  • 描述資源的 {content}
  • 使用 Title Case
  • 示例：Application Logs、Database Table、GitHub Repository
資源模板引數
  • 描述引數的用途
  • 多詞引數使用 camelCase
  • 示例：name、repo、fileType
提示名稱
  • 在 MCP 伺服器內部唯一
  • 描述提示的預期用途
  • 多詞引數使用 camelCase
  • 示例：generateApiRoute、performSecurityReview、analyzeCodeQuality
提示輸入引數
  • 描述引數的用途
  • 多詞引數使用 camelCase
  • 示例：filePath、queryString、userId

開始建立 MCP 伺服器

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

您還可以從 MCP for Beginners 課程 中找到有用的內容，以幫助您開始構建第一個 MCP 伺服器。

相關內容

12/10/2025
© . This site is unofficial and not affiliated with Microsoft.