VS Code 中的 MCP 开发者指南:构建无缝集成 MCP 服务器的完整实战手册

原创2026-10-07 11:48:221,899 阅读
文章标签:文档教程

VS Code 中的 MCP 开发者指南:构建无缝集成 MCP 服务器的完整实战手册

导读:Model Context Protocol(MCP)是连接 AI 模型与外部工具、服务的开放标准。Visual Studio Code 完整实现了 MCP 规范,使开发者能够创建提供工具(Tools)、提示词(Prompts)与资源(Resources)的 MCP 服务器,为 VS Code 中的 AI Agent 扩展能力。本文以官方 MCP 开发者指南 api/extension-guides/ai/mcp.md 为骨架,结合 MCP 配置参考 与 MCP 服务器添加与管理工作流,系统讲解 VS Code 对 MCP 的支持范围、服务器接入与管理方式、扩展内注册服务器的 API 用法、调试排错技巧与命名规范,帮助你从零构建可被 VS Code 及多种 MCP 客户端复用的服务器。

为什么使用 MCP 服务器?

在 VS Code 中,Agent 可用的工具共有三种类型:内置工具、扩展贡献的工具,以及 MCP 服务器提供的工具(详见 工具类型说明)。实现一个 MCP 服务器来扩展 VS Code 聊天中的语言模型工具,具有以下核心收益:

  • 扩展 Agent 模式:以领域专用的工具自动参与用户提示词的响应过程。例如,启用数据库脚手架与查询工具,动态为 LLM 提供相关上下文;
  • 灵活的部署选项:同时覆盖本地与远程两种场景;
  • 跨平台复用:同一 MCP 服务器可在不同工具与平台间重复使用。

与之相对,如果你希望深度集成 VS Code 扩展 API(例如读取调试上下文),或希望通过 Visual Studio Marketplace 分发工具与更新,则应考虑改用 Language Model API 实现语言模型工具。两者取舍详见 AI 扩展能力总览:MCP 工具在 VS Code 之外运行,无法访问 VS Code 扩展 API,但可在其他 MCP 客户端中复用;而语言模型工具深度集成编辑器,但分发与更新依赖 Marketplace。

[!TIP] 如果你只是 MCP 的终端使用者,想了解如何在日常开发中接入并使用 MCP 服务器,请阅读 在 VS Code 中使用 MCP 服务器。

VS Code 支持的 MCP 能力全景

VS Code 对 MCP 规范(以 2025-06-18 规范版本 为准)的支持分为传输层与功能层两个维度:

传输(Transports):

  • 本地标准输入输出(stdio):通过子进程 stdin/stdout 与服务器通信,是本地服务器最常用的方式;
  • Streamable HTTP(http):基于 HTTP 的流式传输;
  • Server-Sent Events(sse):旧版兼容支持。

功能(Features):

能力 说明
Tools 为 Agent 模式 扩展额外工具
Prompts 以聊天斜杠命令形式提供可复用提示词
Resources 提供数据与内容,用户可将其作为聊天上下文或直接在 VS Code 中交互
Elicitation 向用户请求输入
Sampling 使用用户已配置的模型与订阅发起语言模型请求
Authentication 通过 OAuth 授权对 MCP 服务器的访问
Server instructions 服务器指令
Roots 向服务器提供用户工作区根目录信息
MCP Apps 工具可返回交互式 UI 组件

接下来逐一深入这些能力。

Tools:工具定义与运行时行为

VS Code 在 Agent 模式下支持 MCP 工具——工具根据任务需要被自动调用,用户可通过工具选择器(tools picker)启用与配置它们。工具的描述会显示在工具选择器中(与工具名并列),也会出现在执行前确认对话框里:

Agent 模式下显示 MCP 服务器工具的工具选择器截图

用户可以在工具确认对话框中编辑模型生成的输入参数。除非工具标记了 readOnlyHint 注解,否则所有工具执行前都会显示确认对话框:

MCP 工具输入参数确认对话框截图

动态工具发现

VS Code 支持动态工具发现:服务器可以在运行时注册工具。例如,服务器可以根据工作区中检测到的框架或语言提供不同的工具,也可以响应用户的聊天提示词动态调整工具集合。

工具注解

你可以使用工具注解为工具行为提供额外元数据:

  • title:工具的人类可读标题,在工具被调用时显示于 Chat 视图中;
  • readOnlyHint:可选提示,标记工具为只读。VS Code 不会为只读工具弹出确认对话框。

Resources:结构化数据与内容提供

Resources 让你以结构化方式向用户提供数据与内容。用户可以直接在 VS Code 中访问资源,或将其作为聊天提示词的上下文。典型场景:MCP 服务器生成截图并作为资源发布,或提供可实时更新的日志文件。

定义 MCP 资源后,资源名称会出现在 MCP Resources Quick Pick 中。资源可通过 MCP: Browse Resources 命令打开,或通过 Chat 输入框的 Add Context → 选择 MCP Resource 附加到聊天请求。资源可包含文本或二进制内容:

MCP Resources Quick Pick 截图

VS Code 支持资源更新,用户可以在编辑器中实时看到资源内容的变化。

资源模板

VS Code 还支持资源模板,允许用户在引用资源时提供输入参数。例如,数据库查询工具可以询问数据库表名。访问带模板的资源时,VS Code 会在 Quick Pick 中提示用户输入所需参数,你可以提供 completions 来建议参数值。

Prompts:可复用聊天提示词模板

Prompts 是用户可通过斜杠命令(mcp.servername.promptname)调用的可复用聊天提示词模板。Prompts 对引导新用户很有价值:可以突出展示各种工具,或提供能自适应本地上下文与服务的复杂内置工作流。

如果你定义了 completions 来为提示词输入参数提供建议值,VS Code 会显示对话框收集用户输入。下面的 TypeScript 示例定义了一个带 name 参数补全的 teamGreeting 提示词:

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

带输入参数的 MCP 提示词对话框截图

[!NOTE] 用户可以在提示词对话框中输入一条终端命令,并将其命令输出作为提示词的输入。

当你在提示词响应中包含资源类型时,VS Code 会将该资源作为上下文附加到聊天提示词。

授权:OAuth 认证与身份提供者集成

VS Code 支持需要认证的 MCP 服务器,允许服务器代表用户账号为服务操作。MCP 的授权规范将 MCP 服务器(Resource Server)与授权服务器(Authorization Server)清晰分离,开发者可以把认证委托给现有身份提供者(IdP),而无需从零实现 OAuth。

VS Code 内置了 GitHub 与 Microsoft Entra 的认证支持。若你的 MCP 服务器实现最新规范并使用 GitHub 或 Entra 作为授权服务器,用户可以通过 Accounts 菜单 → Manage Trusted MCP Servers 管理哪些 MCP 服务器能访问其账号:

Accounts 菜单中 Manage Trusted MCP Servers 操作截图

对其他 IdP,VS Code 支持基于 OAuth 2.1 与 2.0 标准的授权。流程上 VS Code 先发起 Dynamic Client Registration(DCR) 握手;若 IdP 不支持 DCR,则回退到 client-credentials 流程——这为不同 IdP 按需为每个 MCP 服务器创建静态客户端 ID 或 client ID-secret 对提供了灵活性。用户同样可以通过 Accounts 菜单查看认证状态;移除动态客户端注册则使用命令面板中的 Authentication: Remove Dynamic Authentication Providers 命令。

确保 MCP 服务器与 VS Code 的 OAuth 流程正常工作的检查清单:

  1. MCP 服务器定义了 MCP 授权规范;
  2. IdP 必须支持 DCR 或 client credentials 之一;
  3. 重定向 URL 列表必须包含:http://127.0.0.1:33418 与 https://vscode.dev/redirect。

当服务器不支持 DCR 时,用户将经历 client-credential 回退流程(依次请求动态客户端、客户端 ID、客户端密钥):

DCR 不受支持时的授权流程截图

请求 Client ID 的授权截图

请求 Client Secret 的授权截图

[!NOTE] VS Code 仍兼容作为授权服务器运行的 MCP 服务器,但对新服务器建议使用最新规范。

Sampling:代表用户发起模型请求

VS Code 为 MCP 服务器提供 sampling 访问能力:服务器可以用用户已配置的模型与订阅发起语言模型请求。典型用途包括:在发送给客户端之前先汇总大数据集、提取信息,或在工具内实现 agentic 决策逻辑。

MCP 服务器首次发起 sampling 请求时,用户会被提示授权服务器访问其模型:

MCP 服务器访问模型的授权提示截图

指定具体模型发起请求时需注意:用户可以通过命令面板 MCP: List Servers → Configure Model Access 限制服务器可使用的模型。当你的服务器通过 modelPreferences 提供模型选择提示时,VS Code 会从允许的模型列表中挑选:

MCP 服务器 Configure Model Access 对话框截图

用户可通过 MCP: List Servers → Show Sampling Requests 命令查看服务器发起的 sampling 请求。

工作区根目录(Roots)

VS Code 会向 MCP 服务器提供用户的工作区根文件夹信息,服务器据此感知当前项目上下文。

MCP Apps:交互式 UI 组件

MCP Apps 允许工具返回内联渲染在聊天中的交互式 UI 组件,取代纯文本输出,适用于拖拽列表排序、可视化、表单、多步骤工作流等场景。

架构:Tool + UI Resource 模式

  1. 定义一个返回 _meta.ui.resourceUri(指向 UI 资源)的工具;
  2. 创建使用 ui:// URI scheme、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):发送调试日志(不加入对话)
  • 通知处理器:设置这些回调以接收 VS Code 事件

    • ontoolinput:接收完整工具参数
    • ontoolinputpartial:接收流式部分参数
    • ontoolresult:接收工具执行结果
    • ontoolcancelled:处理工具取消
    • onhostcontextchanged:响应主题或区域设置变化
    • onteardown:卸载前清理

VS Code 行为与限制

功能 VS Code 支持情况
显示模式 仅 inline(不支持 fullscreen 或 pip)
发送消息 填充聊天输入框;不会自动发送
上下文更新 以附件形式呈现
剪贴板写入 支持
摄像头、麦克风、地理位置 不支持

安全

MCP Apps 运行在受 Content Security Policy(CSP)约束的沙箱 iframe 中。定义 UI 资源时,声明你的应用需要访问的域:

  • connectDomains:fetch/XHR 请求的域
  • resourceDomains:图片、字体及其他资源的域
  • frameDomains:可嵌入 iframe 的域

Icons:服务器、资源与工具的图标

VS Code 支持 MCP 服务器、资源与工具上提供的 icons,其 src 属性为指向图片的 URI:

  • 使用 HTTP 或 SSE 传输的服务器:可从服务器所在同一 authority 提供图片(如配置于 https://example.com/mcp 的服务器可提供 example.com 的图片);
  • 使用 stdio 传输的服务器:可通过 file:/// URI 从文件系统提供图片;
  • 任何服务器都可嵌入以 data: 开头的 data URI 图片。

将 MCP 服务器添加到 VS Code

用户可通过多种方式在 VS Code 中添加 MCP 服务器:

  • 网页一键安装:使用特殊的 MCP 安装 URL(vscode:mcp/install);
  • 工作区配置:在工作区 .vscode/mcp.json 文件中指定服务器配置;
  • 全局配置:在用户 配置文件(Profile) 中定义服务器;
  • 自动发现:VS Code 可从 Claude Desktop 等工具中发现服务器;
  • 扩展:VS Code 扩展可通过编程方式注册 MCP 服务器;
  • 命令行:使用 --add-mcp 命令行选项安装。

关于各方式的详细操作(含 Dev Container 内配置 customizations.vscode.mcp、Settings Sync 同步 MCP 配置、服务器信任机制等),见 添加 MCP 服务器。

配置文件格式速览

VS Code 的 MCP 配置有两种文件格式(完整字段参考见 MCP 配置参考):

  • VS Code 格式(.vscode/mcp.json 或用户 Profile 中):顶层使用 servers 对象,VS Code 为该格式提供 IntelliSense;
  • 可移植格式(工作区根目录 .mcp.json 或 ~/.copilot/mcp-config.json):顶层使用 mcpServers 对象,可被 Agent Host 与其他兼容 Copilot 工具直接读取。

以本地 + 远程服务器混合配置为例:

{
    "servers": {
        "github": {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp"
        },
        "playwright": {
            "command": "npx",
            "args": ["-y", "@microsoft/mcp-server-playwright"]
        }
    }
}

stdio 服务器关键字段:type(必填,"stdio")、command(必填,须在系统 PATH 中或含完整路径)、args、cwd(默认工作区文件夹)、env、envFile、dev、sandboxEnabled。使用 Docker 时不要使用 -d 分离模式,服务器必须前台运行以与 VS Code 通信。

HTTP/SSE 服务器关键字段:type("http" 或 "sse")、url、headers、oauth。VS Code 优先尝试 HTTP Stream 传输,不支持时回退到 SSE。还可通过 unix:///path/to/server.sock 或 pipe:///pipe/named-pipe 连接 Unix 套接字与 Windows 命名管道,URL fragment 可指定子路径(如 unix:///tmp/server.sock#/mcp/subpath)。

敏感信息输入变量:使用 ${input:variable-id} 占位符避免硬编码 API 密钥,支持 promptString(密码隐藏输入)、pickString(选项列表)、command(命令输出作为值)三种类型。

管理 MCP 服务器

你可以在 VS Code 的扩展视图(kb(workbench.view.extensions))中管理已安装的 MCP 服务器列表:

扩展视图中显示的 MCP 服务器截图

右键点击 MCP 服务器或选择齿轮图标执行管理操作;也可运行命令面板的 MCP: List Servers 查看并操作配置的服务器。

[!TIP] 打开 .vscode/mcp.json 文件时,VS Code 会在编辑器中显示代码透镜(code lens)命令,可直接在编辑器内启动、停止或重启服务器。

带管理服务器的代码透镜的 MCP 配置截图

相关的 MCP 管理命令还包括:MCP: Add Server(引导式添加)、MCP: Browse Resources(浏览资源)、MCP: Reset Cached Tools(服务器工具变化后清除缓存)、MCP: Reset Trust(重置非工作区来源服务器的信任决策)、MCP: Open User Configuration / Open Workspace Folder Configuration 等,完整命令表见 MCP 配置参考。

创建 MCP 安装 URL

VS Code 提供 vscode:mcp/install?{json-configuration} URL 处理器(Insiders 为 vscode-insiders:mcp/install?{json-configuration}),用于从链接安装 MCP 服务器。

以 {\"name\":\"server-name\",\"command\":...} 形式提供 JSON 服务器配置,然后执行 JSON 字符串化与 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 实现该提供者。

[!NOTE] 从源码结构看,vscode.lm 命名空间承载了语言模型相关的全部 API,registerMcpServerDefinitionProvider 与 Language Model Tool 相关 API(参见 Language Model Tool API)同属该命名空间;也可参考官方 mcp-extension-sample 示例项目快速起步。

第 1 步:package.json 静态配置

扩展必须贡献 contributes.mcpServerDefinitionProviders 入口点,其 id 应与实现中使用的保持一致:

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

第 2 步:实现提供者

使用 vscode.lm.registerMcpServerDefinitionProvider API 提供服务器的 MCP 配置。API 接收一个 providerId 字符串和一个 McpServerDefinitionProvider 对象。

McpServerDefinitionProvider 对象包含三个属性:

  • onDidChangeMcpServerDefinitions:MCP 服务器配置变化时触发的事件;
  • provideMcpServerDefinitions:返回 MCP 服务器配置数组(vscode.McpServerDefinition[])的函数;
  • resolveMcpServerDefinition:编辑器需要启动 MCP 服务器时调用的函数,可用于执行可能需要用户交互的附加操作(如认证)。

McpServerDefinition 对象有两种类型:

  • vscode.McpStdioServerDefinition:表示通过本地进程的 stdin/stdout 流运行的服务器;
  • vscode.McpHttpServerDefinition:表示使用 Streamable HTTP 传输的服务器。

以下示例演示如何在扩展中注册 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: 'http://localhost: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;
        }
    }));
}

[!NOTE] resolveMcpServerDefinition 返回 undefined 或抛出错误时,服务器不会启动;若有挂起的工具调用,编辑器会将其取消并向语言模型返回错误消息。

排错与调试 MCP 服务器

VS Code 中的 MCP 开发模式

开发 MCP 服务器时,可在配置中添加 dev 键启用开发模式,包含两个属性:

  • watch:glob 模式(或 glob 模式数组),监视文件变化并重启 MCP 服务器;
  • debug:为 MCP 服务器配置调试器。当前支持调试 Node.js 与 Python 两种 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 服务器:设置 debug.type 为 debugpy,若默认 Python 环境未安装 debugpy 模块,可选设置 debug.debugpyPath 指向其路径:

{
    "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 服务器问题,会在 Chat 视图显示错误指示器:

MCP 服务器错误截图

点击 Chat 视图中的错误通知,选择 Show Output 查看服务器日志;或者运行命令面板 MCP: List Servers,选中服务器后选择 Show Output:

MCP 服务器错误输出截图

[!TIP] 若服务器无法启动,还可检查:命令参数是否正确、使用 Docker 时容器是否处于分离模式(-d)、沙箱(sandboxEnabled)配置是否拦截了服务器所需的文件系统/网络访问(见 MCP 配置参考 中的错误排查提示)。

最佳实践

核心最佳实践清单:

  • 命名规范:确保名称唯一且具描述性;
  • 完善的错误处理与校验:提供有描述性的错误消息;
  • 使用进度报告:告知用户长耗时操作的进展;
  • 保持工具操作聚焦且原子化:避免复杂交互;
  • 清晰记录工具:工具描述应帮助用户理解何时使用;
  • 优雅处理缺失输入参数:提供默认值或清晰错误消息;
  • 为资源设置 MIME 类型:确保 VS Code 正确处理不同内容类型;
  • 使用资源模板:允许用户访问资源时提供输入参数;
  • 缓存资源内容:提升性能、减少不必要的网络请求;
  • 为 sampling 请求设置合理 token 上限:避免过度消耗资源;
  • 校验 sampling 响应:使用前先验证。

命名规范参考表

组件 命名规范
工具名 服务器内唯一;描述动作与动作对象;使用 snake_case,格式 {verb}_{noun};示例:generate_report、fetch_data、analyze_code
工具输入参数 描述参数用途;多词参数使用 camelCase;示例:path、queryString、userId
资源名 服务器内唯一;描述资源内容;使用 title case;示例:Application Logs、Database Table、GitHub Repository
资源模板参数 描述参数用途;多词参数使用 camelCase;示例:name、repo、fileType
提示词名 服务器内唯一;描述提示词预期用途;多词参数使用 camelCase;示例:generateApiRoute、performSecurityReview、analyzeCodeQuality
提示词输入参数 描述参数用途;多词参数使用 camelCase;示例:filePath、queryString、userId

服务器名称本身建议使用 camelCase(如 uiTesting、githubIntegration),避免空白字符与特殊字符,名称须唯一且能反映功能或品牌。

开始创建你的 MCP 服务器

VS Code 提供了开发 MCP 服务器所需的全部工具。虽然任何能处理 stdout 的语言都可以编写 MCP 服务器,但官方 SDK 是最好的起点:TypeScript SDK、Python SDK、Java SDK、Kotlin SDK、C# SDK。初学者还可参考 Microsoft 的 "MCP for Beginners" 课程,从构建第一个 MCP 服务器开始上手。

相关阅读

登录后查看全文
vscode-docs