💻 歡迎參加 6 月 3 日舉行的 MS Build 之 VS Code 直播活動。

MCP 開發者指南

模型上下文協定 (Model Context Protocol, MCP) 是一項開放標準，能讓 AI 模型透過統一的介面與外部工具和服務互動。Visual Studio Code 完整實作了 MCP 規範，讓您能夠建立提供工具、提示詞 (Prompts) 和資源的 MCP 伺服器，以擴充 VS Code 中 AI 代理程式的能力。

除了內建工具和擴充功能提供的工具外，MCP 伺服器還提供了 VS Code 中三種可用工具類型中的其中一種。進一步了解工具類型。

本指南涵蓋了您開發能與 VS Code 及其他 MCP 客戶端無縫協作的 MCP 伺服器所需的一切知識。

提示

若需了解終端使用者如何使用 MCP 伺服器，請參閱在 VS Code 中使用 MCP 伺服器。

為什麼要使用 MCP 伺服器？

實作 MCP 伺服器以透過語言模型工具擴充 VS Code 的聊天功能，具有以下優點：

  • 擴充代理程式模式 (Agent mode)：使用專門的領域工具，這些工具會在回應使用者提示詞時自動調用。例如，啟用資料庫構建與查詢功能，動態地為 LLM 提供相關上下文。
  • 靈活的部署選項：適用於本機與遠端情境。
  • 重複使用性：您的 MCP 伺服器可在不同的工具與平台上重複使用。

在以下情境中，您可能會考慮使用語言模型 API (Language Model API) 來實作語言模型工具：

  • 您希望透過使用擴充功能 API 與 VS Code 進行深度整合。
  • 您希望透過 Visual Studio Marketplace 發布您的工具及更新。

VS Code 支援的 MCP 功能

VS Code 支援下列 MCP 功能：

  • 傳輸協定 (Transports):

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

  • 功能:

    • 工具：使用額外工具擴充代理程式模式
    • 提示詞：在聊天中以斜線指令 (slash commands) 的形式新增可重複使用的提示詞
    • 資源：提供使用者可新增為聊天上下文，或在 VS Code 中直接互動的資料與內容
    • 啟發 (Elicitation)：向使用者要求輸入
    • 取樣 (Sampling)：使用使用者已設定的模型與訂閱來發送語言模型請求
    • 驗證 (Authentication)：使用 OAuth 授權存取 MCP 伺服器
    • 伺服器指令 (Server instructions)
    • 根目錄 (Roots)：提供有關使用者工作區根目錄的資訊
    • MCP Apps：從工具返回互動式 UI 元件

工具

工具定義

VS Code 在代理程式模式下支援 MCP 工具，這些工具會根據任務需求進行調用。使用者可以透過工具選擇器 (tools picker) 啟用並設定它們。工具描述會與工具名稱一起顯示在工具選擇器中，並在執行工具前要求確認的對話框中顯示。

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 資源快速選單 (Quick Picks) 中。資源可以透過 MCP: 瀏覽資源 指令開啟，或透過 新增上下文 並選擇 MCP 資源 將其附加到聊天請求中。資源可包含文字或二進位內容。

Screenshot that shows the MCP Resources Quick Pick.

VS Code 支援資源更新，讓使用者能在編輯器中即時查看資源內容的變更。

資源範本

VS Code 也支援資源範本，讓使用者在參照資源時提供輸入參數。例如，資料庫查詢工具可以詢問資料庫資料表的名稱。

當使用範本存取資源時，系統會提示使用者在快速選單中輸入所需參數。您可以提供自動完成建議來協助填寫參數值。

提示詞

提示詞是可重複使用的聊天提示詞範本，使用者可以在聊天中透過斜線指令 (mcp.servername.promptname) 來調用。提示詞對於向使用者介紹您的伺服器很有幫助，可以突顯各種工具，或提供適應使用者本機上下文與服務的內建複雜工作流程。

如果您定義了自動完成 (completions) 來建議提示詞輸入參數的值，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 標準以及針對除 GitHub 和 Microsoft Entra 外的其他 IdP 的 2.0 標準進行授權。VS Code 首先以 動態客戶端註冊 (DCR) 交握開始，如果 IdP 不支援 DCR，則會回退到客戶端憑證 (client-credentials) 工作流程。這使得各種 IdP 能夠更靈活地為每個 MCP 伺服器建立靜態客戶端 ID 或特定的客戶端 ID-密鑰對。

使用者隨後也能透過 帳戶選單 查看其授權狀態。若要移除動態客戶端註冊，使用者可以使用指令面板中的 驗證：移除動態驗證提供者 指令。

以下是確保您的 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 伺服器，但建議新伺服器使用最新規範。

取樣 (Sampling)

VS Code 為 MCP 伺服器提供了取樣 (sampling) 存取權。這允許您的 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 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)：傳送除錯日誌（不會加入對話內容）。

  • 通知處理常式 (Notification handlers)：設定這些處理常式以接收來自 VS Code 的事件。

    • ontoolinput：接收完整的工具參數。
    • ontoolinputpartial：接收串流的部分參數。
    • ontoolresult：接收工具執行結果。
    • ontoolcancelled：處理工具取消事件。
    • onhostcontextchanged：回應佈景主題或語言設定的變更。
    • onteardown：在解除掛載前進行清理。

VS Code 行為與限制

功能 VS Code 支援
顯示模式 僅限 inline (不支援 fullscreen 或 pip)
傳送訊息 填入聊天輸入框；不會自動傳送
上下文更新 顯示為附件
剪貼簿寫入 支援
相機、麥克風、地理位置 不支援

安全性

MCP Apps 在強制執行內容安全性政策 (CSP) 的沙盒 iframe 中執行。當定義 UI 資源時，請宣告您的應用程式需要存取的網域：

  • connectDomains：用於 fetch/XHR 請求的網域。
  • resourceDomains：用於圖片、字型及其他資源的網域。
  • frameDomains：可以嵌入 iframe 的網域。

深入了解

圖示

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

  • 使用 HTTP 或 SSE 傳輸協定的 MCP 伺服器，可以從託管 MCP 伺服器的同一來源提供圖片。例如，設定於 https://example.com/mcp 的伺服器可以從 example.com 提供圖片。
  • 使用 stdio 傳輸協定的 MCP 伺服器，可以使用 file:/// URI 從檔案系統提供圖片。
  • 任何 MCP 伺服器都可以將圖片嵌入為以 data: 開頭的資料 URI。

在 VS Code 中新增 MCP 伺服器

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

  • 直接從網頁安裝：使用您網站上的特殊 MCP 安裝 URL (vscode:mcp/install)。
  • 工作區設定：在工作區的 .vscode/mcp.json 檔案中指定伺服器設定。
  • 全域設定：在使用者設定檔 (profile) 中定義全域伺服器。
  • 自動探索：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: 列出伺服器 指令以檢視已設定的 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 伺服器定義提供者。

您可以參考如何在 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：代表透過執行本機處理序並在其 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 金鑰來啟用 開發模式 (development mode)。這是一個包含兩個屬性的物件：

  • watch：一個 Glob 模式或 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

選取聊天視圖中的錯誤通知，然後選擇 顯示輸出 選項以查看伺服器日誌。或者，從指令面板執行 MCP: 列出伺服器，選擇該伺服器，然後選擇 顯示輸出。

MCP Server Error Output

最佳實踐

  • 命名規範，確保名稱具有唯一性與描述性。
  • 實作正確的錯誤處理與驗證，並附上具描述性的錯誤訊息。
  • 使用進度回報，讓使用者了解長時間執行的操作狀態。
  • 保持工具操作專注且原子化 (atomic)，以避免複雜的互動。
  • 清楚記錄您的工具，提供描述以幫助使用者了解何時使用它們。
  • 優雅地處理缺少的輸入參數，提供預設值或清楚的錯誤訊息。
  • 為資源設定 MIME 類型，確保 VS Code 能正確處理不同類型的內容。
  • 使用資源範本，允許使用者在存取資源時提供輸入參數。
  • 快取資源內容，以提升效能並減少不必要的網路請求。
  • 為取樣請求設定合理的 Token 限制，以避免資源過度使用。
  • 在使用前驗證取樣回應。

命名規範

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

元件 命名規範準則
工具名稱
  • 在 MCP 伺服器內具有唯一性
  • 描述動作及其動作目標
  • 使用蛇形命名法 (snake case)，結構為 {動詞}_{名詞}
  • 範例：generate_report、fetch_data、analyze_code
工具輸入參數
  • 描述參數用途
  • 多單字參數使用駝峰命名法 (camelCase)
  • 範例：path、queryString、userId
資源名稱
  • 在 MCP 伺服器內具有唯一性
  • 描述資源內容
  • 使用標題列命名法 (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 初學者課程 (MCP for Beginners curriculum) 對於開始建置您的第一個 MCP 伺服器很有幫助。

相關內容

5/28/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.