MCP 開發人員指南

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

MCP 伺服器提供了 VS Code 中可用的三種工具類型之一（與內建工具和擴充功能提供的工具並列）。深入了解工具類型。

本指南涵蓋了建構能與 VS Code 及其他 MCP 用戶端無縫協作的 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 伺服器
  • 伺服器指示
  • 根目錄：提供有關使用者工作區根資料夾的資訊
  • MCP 應用程式：從工具傳回互動式 UI 元件

工具

工具定義

VS Code 在代理程式模式下支援 MCP 工具，這些工具會根據任務視需要被叫用。使用者可以使用工具選擇器來啟用和設定它們。工具描述會顯示在工具選擇器中（與工具名稱並列），以及在執行工具前要求確認的對話方塊中。

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

動態工具探索

VS Code 也支援動態工具探索，允許伺服器在執行階段註冊工具。例如，伺服器可以根據工作區中偵測到的框架或語言，或回應使用者的對話提示詞，來提供不同的工具。

工具註釋

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

• title：工具的人類可讀標題，當叫用工具時會顯示在「對話」檢視區中
• readOnlyHint：選用的提示，用以指出該工具是唯讀的。VS Code 在執行唯讀工具時不會要求確認。

資源

資源讓您能以結構化方式向使用者提供資料與內容。使用者可以直接在 VS Code 中存取資源，或在對話提示詞中將其用作上下文。例如，MCP 伺服器可以產生螢幕擷取畫面並將其作為資源提供，或是提供對記錄檔案的存取，然後即時更新這些檔案。

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

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 會將該資源作為上下文附加到對話提示詞中。

授權

VS Code 支援需要驗證的 MCP 伺服器，允許使用者與代表該服務的使用者帳戶運作的 MCP 伺服器進行互動。

授權規格清楚地將作為資源伺服器的 MCP 伺服器與授權伺服器區分開來，讓開發人員可以將驗證委派給現有的身分識別提供者（IdP），而不必從頭建構自己的 OAuth 實作。

VS Code 對 GitHub 和 Microsoft Entra 具有內建的驗證支援。如果您的 MCP 伺服器實作了最新規格，並使用 GitHub 或 Microsoft Entra 作為授權伺服器，使用者即可透過該帳戶的帳戶功能表 > 管理受信任的 MCP 伺服器動作，來管理哪些 MCP 伺服器有權存取其帳戶。

VS Code 支援使用 OAuth 2.1 標準和 2.0 標準對 GitHub 和 Microsoft Entra 以外的其他 IdP 進行授權。VS Code 首先會透過動態用戶端註冊 (DCR) 交握開始，如果 IdP 不支援 DCR，則會回復為用戶端憑證工作流程。這讓各種 IdP 更有彈性地為每個 MCP 伺服器建立靜態用戶端 ID 或特定的用戶端 ID-密碼配對。

使用者隨後也可以透過帳戶功能表檢視其驗證狀態。若要移除動態用戶端註冊，使用者可以在命令選擇區中使用 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 時，使用者將會透過備援的用戶端憑證流程進行

取樣

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 應用程式

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

架構

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

1. 定義一個傳回指向 UI 資源之 _meta.ui.resourceUri 的工具
2. 建立一個具有 ui:// URI 配置與 MIME 類型 text/html;profile=mcp-app 的 UI 資源
3. HTML 資源會在隔離的 iframe 中執行，並使用 MCP Apps SDK 與 VS Code 通訊

SDK

使用 @modelcontextprotocol/ext-apps 套件來建構 MCP 應用程式。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 應用程式會在強制執行內容安全性政策 (CSP) 的隔離 iframe 中執行。當定義 UI 資源時，請宣告您的應用程式需要存取的網域：

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

深入了解

• MCP 應用程式規格
• MCP Apps SDK 與範例
• 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 伺服器：

• 從網頁直接安裝：在您的網站上使用特殊的 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 伺服器清單。

以滑鼠右鍵按一下 MCP 伺服器或選取齒輪圖示，即可對伺服器執行不同的管理動作。或者，從命令選擇區執行 MCP: List Servers 命令來檢視已設定的 MCP 伺服器清單。然後，您可以選取伺服器並對其執行動作。

建立 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 中貢獻帶有提供者 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 伺服器。

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：用於監視檔案變更以重新啟動 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，如果 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 伺服器的問題時，它會在「對話」檢視區中顯示錯誤指示器。

選取「對話」檢視區中的錯誤通知，然後選取顯示輸出選項來檢視伺服器記錄。或者，從命令選擇區執行 MCP: List Servers，選取伺服器，然後選擇顯示輸出。

最佳做法

• 命名慣例以確保名稱具有唯一性與描述性
• 實作適當的錯誤處理與驗證，並附帶具描述性的錯誤訊息
• 使用進度回報來通知使用者執行時間較長的作業
• 保持工具作業專注且具備不可分割性，以避免複雜的互動
• 清楚記錄您的工具，並提供能協助使用者了解何時使用它們的描述
• 妥善處理遺失的輸入參數，方法是提供預設值或清晰的錯誤訊息
• 為資源設定 MIME 類型，以確保在 VS Code 中正確處理不同的內容類型
• 使用資源範本，允許使用者在存取資源時提供輸入參數
• 快取資源內容以提升效能並減少不必要的網路要求
• 為取樣要求設定合理的權杖限制，以避免過度使用資源
• 在使用取樣回應之前進行驗證

命名慣例

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

開始建立 MCP 伺服器

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

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

您可能也會覺得初學者 MCP 課程對於開始建構您的第一個 MCP 伺服器很有幫助。

相關內容

• 貢獻語言模型工具
• 在代理程式模式下使用 MCP 工具
• VS Code 精選的 MCP 伺服器清單
• 模型上下文協定文件