VS Code 中的 MCP 开发者指南:构建无缝集成 MCP 服务器的完整实战手册
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)启用与配置它们。工具的描述会显示在工具选择器中(与工具名并列),也会出现在执行前确认对话框里:
用户可以在工具确认对话框中编辑模型生成的输入参数。除非工具标记了 readOnlyHint 注解,否则所有工具执行前都会显示确认对话框:
动态工具发现
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 附加到聊天请求。资源可包含文本或二进制内容:
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!` }
}]
})
);
[!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 服务器能访问其账号:
对其他 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 流程正常工作的检查清单:
- MCP 服务器定义了 MCP 授权规范;
- IdP 必须支持 DCR 或 client credentials 之一;
- 重定向 URL 列表必须包含:
http://127.0.0.1:33418与https://vscode.dev/redirect。
当服务器不支持 DCR 时,用户将经历 client-credential 回退流程(依次请求动态客户端、客户端 ID、客户端密钥):
[!NOTE] VS Code 仍兼容作为授权服务器运行的 MCP 服务器,但对新服务器建议使用最新规范。
Sampling:代表用户发起模型请求
VS Code 为 MCP 服务器提供 sampling 访问能力:服务器可以用用户已配置的模型与订阅发起语言模型请求。典型用途包括:在发送给客户端之前先汇总大数据集、提取信息,或在工具内实现 agentic 决策逻辑。
MCP 服务器首次发起 sampling 请求时,用户会被提示授权服务器访问其模型:
指定具体模型发起请求时需注意:用户可以通过命令面板 MCP: List Servers → Configure Model Access 限制服务器可使用的模型。当你的服务器通过 modelPreferences 提供模型选择提示时,VS Code 会从允许的模型列表中挑选:
用户可通过 MCP: List Servers → Show Sampling Requests 命令查看服务器发起的 sampling 请求。
工作区根目录(Roots)
VS Code 会向 MCP 服务器提供用户的工作区根文件夹信息,服务器据此感知当前项目上下文。
MCP Apps:交互式 UI 组件
MCP Apps 允许工具返回内联渲染在聊天中的交互式 UI 组件,取代纯文本输出,适用于拖拽列表排序、可视化、表单、多步骤工作流等场景。
架构:Tool + UI Resource 模式
- 定义一个返回
_meta.ui.resourceUri(指向 UI 资源)的工具; - 创建使用
ui://URI scheme、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):请求在浏览器中打开 URLsendLog(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: List Servers 查看并操作配置的服务器。
[!TIP] 打开
.vscode/mcp.json文件时,VS Code 会在编辑器中显示代码透镜(code lens)命令,可直接在编辑器内启动、停止或重启服务器。
相关的 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 服务器需要两步:
- 在扩展的
package.json中定义 MCP 服务器定义提供者(定义入口点); - 在扩展代码中使用
vscode.lm.registerMcpServerDefinitionProviderAPI 实现该提供者。
[!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 视图显示错误指示器:
点击 Chat 视图中的错误通知,选择 Show Output 查看服务器日志;或者运行命令面板 MCP: List Servers,选中服务器后选择 Show Output:
[!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 服务器开始上手。













