MCP 開發者指南

Name: Visual Studio Code
Author: Microsoft

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

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

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

提示

若需以終端使用者身分使用 MCP 伺服器的相關資訊，請參閱在 VS Code 中使用 MCP 伺服器。

為什麼要使用 MCP 伺服器？

實作 MCP 伺服器以利用語言模型工具來擴充 VS Code 的對話功能，具有以下優點：

擴充代理程式模式 (Agent mode)：使用專門的領域特定工具，這些工具會在回應使用者提示時自動呼叫。例如，啟用資料庫腳本生成與查詢，以動態方式為大型語言模型 (LLM) 提供相關背景資訊。
彈性的部署選項：適用於本機與遠端情境。
重複使用性：在不同的工具與平台間重複使用您的 MCP 伺服器。

若有下列情境，您可能會考慮使用語言模型 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 伺服器
- 伺服器指令
- 根目錄 (Roots)：提供有關使用者工作區根目錄資料夾的資訊
- MCP Apps：從工具回傳互動式 UI 元件

工具

工具定義

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: Browse Resources 指令開啟，或是透過「加入背景資訊」(Add Context) 後選擇「MCP 資源」來附加到對話請求中。資源可包含文字或二進位內容。

Screenshot that shows the MCP Resources Quick Pick.

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

資源範本

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

當存取具有範本的資源時，系統會提示使用者在快速選擇器中輸入所需的參數。您可以提供補完功能，為參數建議數值。

提示詞 (Prompts)

提示詞是可重複使用的對話提示範本，使用者可以在對話中使用斜線命令 (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 伺服器作為「資源伺服器」(Resource Servers) 與「授權伺服器」(Authorization Servers) 明確分開，讓開發者能夠委託現有的身分提供者 (IdPs) 進行驗證，而不需從頭建置自己的 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 的其他 IdPs 進行授權。VS Code 會先從動態客戶端註冊 (DCR) 交握開始，若 IdP 不支援 DCR，則會退回到客戶端憑證 (client-credentials) 工作流程。這賦予了不同 IdP 更多彈性，可針對每個 MCP 伺服器建立靜態客戶端 ID 或特定的客戶端 ID-密鑰對。

使用者隨後也可透過「帳戶選單」查看其驗證狀態。若要移除動態客戶端註冊，使用者可以使用命令面板中的「驗證：移除動態驗證提供者」(Authentication: Remove Dynamic Authentication Providers) 指令。

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

取樣 (Sampling)

VS Code 為 MCP 伺服器提供取樣 (Sampling) 的存取權。這允許您的 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 伺服器。

MCP Apps

MCP Apps 讓工具能回傳互動式 UI 元件，在對話中以內嵌方式渲染，而非僅僅是文字輸出。這對於拖放清單重新排序、視覺化、表單與多步驟工作流程等情境非常有用。

架構

MCP Apps 使用「工具 + UI 資源」模式

定義一個回傳 _meta.ui.resourceUri 的工具，該 URI 指向一個 UI 資源。
建立一個使用 ui:// URI 配置且 MIME 類型為 text/html;profile=mcp-app 的 UI 資源。
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 伺服器的同一來源 (authority) 服務圖片。例如，設定於 https://example.com/mcp 的伺服器可以從 example.com 服務圖片。
使用 stdio 傳輸的 MCP 伺服器可以使用 file:/// URI 從檔案系統服務圖片。
任何 MCP 伺服器皆可以將圖片作為以 data: 開頭的 data URI 嵌入。

將 MCP 伺服器加入 VS Code

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

從網頁直接安裝：在您的網站上使用特殊的 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})。

提供 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 伺服器，您需要執行下列步驟：

在您的擴充功能 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：代表透過執行本機處理程序並在其 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 模式，用於監看檔案變更並重啟 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 伺服器相關問題時，會在「對話」檢視中顯示錯誤指示器。

選取對話檢視中的錯誤通知，然後選取「顯示輸出」(Show Output) 選項以查看伺服器日誌。或者，從命令面板執行「MCP: List Servers」，選取伺服器，然後選擇「顯示輸出」。

MCP Server Error Output

最佳實踐

命名慣例：確保名稱具唯一性且具描述性。
實作正確的錯誤處理與驗證：提供具描述性的錯誤訊息。
使用進度報告：向使用者通知長時間執行的操作。
保持工具操作專注且原子化：避免複雜的互動。
清楚記載您的工具：提供有助於使用者理解何時使用它們的說明。
優雅地處理缺失的輸入參數：提供預設值或清楚的錯誤訊息。
為資源設定 MIME 類型：確保 VS Code 能正確處理不同的內容類型。
使用資源範本：允許使用者在存取資源時提供輸入參數。
快取資源內容：改善效能並減少不必要的網路請求。
為取樣請求設定合理的 Token 限制：避免過度使用資源。
驗證取樣回應：在使用前進行驗證。

命名慣例

建議對 MCP 伺服器及其元件採用下列命名慣例：

元件	命名慣例指南
工具名稱	在 MCP 伺服器內具有唯一性描述操作以及操作的目標使用 snake_case，結構為 `{verb}_{noun}` 範例：`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 伺服器有所幫助。

4/8/2026