MCP 开发者指南

Name: Visual Studio Code
Author: Microsoft

模型上下文协议（MCP）是一个开放标准，使人工智能模型能够通过统一界面与外部工具和服务交互。Visual Studio Code 实现了完整的 MCP 规范，使你能够创建 MCP 服务器，提供工具、提示和资源，以扩展 VS Code 中 AI 代理的能力。

MCP 服务器提供了 VS Code 中三种工具之一，此外还有内置工具和扩展贡献的工具。了解更多关于工具类型的介绍。

本指南涵盖了构建与VS Code及其他MCP客户端无缝协作的MCP服务器所需的一切。

提示

有关作为终端用户使用 MCP 服务器的信息，请参见 VS Code 中使用 MCP 服务器。

为什么要用MCP服务器？

通过语言模型工具实现MCP服务器以在VS Code中扩展聊天具有以下好处：

通过专门的领域专用工具扩展代理模式，这些工具在响应用户提示时会自动调用。例如，启用数据库支架和查询功能，动态地为LLM提供相关上下文。
本地和远程场景的灵活部署选项。
在不同工具和平台上重复使用你的MCP服务器。

你可以考虑在以下情景下实现带有语言模型API的语言模型工具：

你需要通过使用扩展API深度集成VS Code。
你想通过Visual Studio市场分发你的工具和更新。

VS Code 支持 MCP 功能

VS Code 支持以下 MCP 功能：

传输工具：
- 本地标准输入/输出（标准)
- 可流式HTTP （http)
- 服务器发送事件（SSE）——遗留支持。
特色：
- 工具：用额外工具扩展代理模式
- 提示词：在聊天中添加可重复使用的提示，作为同人命令
- 资源：提供用户可作为聊天上下文或直接在VS Code中交互的数据和内容
- 引发：向用户请求输入
- 采样：利用用户配置的模型和订阅发送语言模型请求
- 认证：授权使用 OAuth 访问 MCP 服务器
- 服务器指令
- 根：提供用户工作区根文件夹的信息
- MCP 应用：返回工具中的交互式 UI 组件

工具

工具定义

VS Code 支持代理模式下的 MCP 工具，根据任务需求调用。用户可以使用工具选择器启用和配置这些工具。工具描述会显示在工具选择器中，与工具名称并列，并在运行工具前请求确认时的对话框中显示。

截图显示了代理模式下的工具选择器，突出显示了MCP服务器上的工具。

用户可以在工具确认对话框中编辑模型生成的输入参数。所有未标记仅读提示注释。

这是显示MCP工具输入参数确认对话框的截图。

动态工具发现

VS Code 还支持动态工具发现，允许服务器在运行时注册工具。例如，服务器可以根据工作区检测到的框架或语言，或响应用户的聊天提示，提供不同的工具。

工具注释

为了提供关于工具行为的额外元数据，可以使用工具注释：

标题：工具的人类可读标题，在聊天视图中显示工具被调用时
仅读提示：可选提示，表示该工具是只读的。VS Code 运行只读工具时不会要求确认。

资源

资源使你能够以结构化的方式向用户提供数据和内容。用户可以直接访问VS Code中的资源，或在聊天提示中将其作为上下文使用。例如，MCP服务器可以生成截图并作为资源提供，或者提供日志文件访问，日志文件会实时更新。

当你定义 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!` }
      }
    ]
  })
);

截图显示了MCP提示词的对话框，并带有输入参数。

注释

用户可以在提示对话框中输入终端命令，并以命令输出作为提示输入。

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

授权

VS Code 支持需要认证的 MCP 服务器，允许用户与代表其用户账户运行的 MCP 服务器进行交互。

授权规范清晰地将 MCP 服务器作为资源服务器与授权服务器区分开来，允许开发者将认证委托给现有身份提供者（IdP），而无需从零构建自己的 OAuth 实现。

VS Code 内置了 GitHub 和 Microsoft Entra 的认证支持。如果你的 MCP 服务器实现了最新规范，并使用 GitHub 或 Microsoft Entra 作为授权服务器，用户可以通过账户菜单>“管理可信 MCP 服务器”作来管理哪些 MCP 服务器有权限访问他们的账户。

显示账户菜单和“管理受信任MCP服务器”作的截图。

VS Code 支持使用 OAuth 2.1 标准和 2.0 标准授权，适用于除 GitHub 和 Microsoft Entra 以外的其他 IdP。VS Code 首先通过动态客户端注册（DCR）握手，如果 IdP 不支持 DCR，则会退回到客户端凭证流程。这为各 IdP 提供了更多灵活性，可以根据每个 MCP 服务器创建静态客户端 ID 或特定的客户端 ID 与秘密对。

用户还可以通过账户菜单查看自己的认证状态。要移除动态客户端注册，用户可以在命令面板中使用“认证：移除动态认证提供者”命令。

以下是一份检查清单，以确保您的MCP服务器和VS Code的OAuth工作流程能够正常运行：

MCP服务器定义了MCP授权规范。
IdP 必须支持 DCR 或客户端凭证
重定向URL列表必须包含以下URL：http://127.0.0.1:33418以及https://vscode.dev/redirect

当MCP服务器不支持DCR时，用户将经历备份客户端凭证流程：

这张截图显示了MCP服务器不支持DCR时的授权情况。

截图显示了请求MCP服务器客户端ID时的授权情况。

截图显示了请求MCP服务器客户端密钥时的授权情况。

注释

VS Code 仍支持作为授权服务器的 MCP 服务器，但建议新服务器使用最新规范。

采样

VS Code 为 MCP 服务器提供采样访问。这使得MCP服务器能够利用用户配置的模型和订阅发送语言模型请求。例如，利用抽样来汇总大型数据集，提取信息后再发送给客户端，或在工具中实现代理决策逻辑。

MCP服务器首次执行采样请求时，会提示用户授权服务器访问其模型。

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

在对特定模型进行采样请求时，考虑用户可以在命令面板中限制MCP服务器可使用哪些模型：列表服务器>配置模型访问命令。当你指定时模型偏好在你的MCP服务器中，为了提供采样所需的提示，VS Code会从允许的模型中选择。

显示MCP服务器配置模型访问对话框的截图。

用户可以通过命令面板中的 MCP： List Servers > Show Sampling Requests 命令查看 MCP 服务器发出的采样请求。

工作空间的根源

VS Code 向 MCP 服务器提供用户的工作区根文件夹信息。

MCP应用

MCP 应用支持工具返回交互式 UI 组件，这些组件在聊天中内联渲染，而非仅输出文本。这适用于拖拽列表重排序、可视化、表单和多步工作流程等场景。

Architecture

MCP 应用采用工具 + UI 资源模式：

定义一个返回_meta.ui.resourceUri指向一个UI资源
创建一个带有ui://URI方案与MIME类型文本/HTML;profile=mcp-app
HTML资源运行在沙盒iframe中，并使用MCP Apps SDK与VS Code通信

SDK

使用该@modelcontextprotocol/ext-apps用于构建MCP应用的包。SDK提供：

应用级别：与主机通信的主要接口
- connect（）：建立与VS代码的联系
- callServerTool（name， args）：起源MCP服务器上的调用工具
- sendMessage（内容）：向聊天输入发送消息
- 更新模型上下文（context）：为未来的对话提供背景
- openLink（URL）：请求在浏览器中打开一个URL。
- sendLog（级别，消息）：发送调试日志（不添加到对话中）
通知处理程序：将它们设置为接收来自VS Code的事件
- ONTOOL输入：接收完整的工具参数
- ontoolinputpartial：接收流式部分论证
- OnTool结果：接收工具执行结果
- 在Tool取消：手柄工具消除
- onhostcontextchanged：对主题或地点变化做出反应
- 拆除：卸载前先清理

VS 代码的行为与局限性

特色	VS Code 支持
显示模式	`直排`只是（不是`全屏`或`PIP`)
发送消息	填充聊天输入框;不自动发送
背景更新	作为附件出现
剪贴板书写	支持
摄像头、麦克风、地理定位	不支持。

安全性

MCP 应用运行在带有内容安全策略（CSP）强制执行的沙箱 iframe 中。定义 UI 资源时，请声明你的应用需要访问的域：

connectDomains：用于获取/XHR请求的域
resourceDomains：图片、字体及其他资源的域名
框架域：可以嵌入iframe中的域

了解更多

图标

VS Code 支持图标在MCP服务器、资源和工具上提供。MCP图标有SRC该属性是图像的URI：

使用 HTTP 或 SSE 传输的 MCP 服务器可以从与 MCP 服务器托管的同一权威机构提供图像。例如，配置为https://example.com/mcp可以从以下地区提供图像example.com.
使用 stdio 传输的 MCP 服务器可以通过以下方式从文件系统提供图像file:///上呼吸道。
任何MCP服务器都可以将图像嵌入为以以下开头的数据URI形式数据：.

将MCP服务器添加到VS Code中

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

直接从网页安装：使用特殊的 MCP 安装 URL （VScode：MCP/install）在你的网站上。
工作区配置：在.vscode/mcp.json工作区中的文件。
全局配置：在用户配置文件中定义全局服务器。
自动发现：VS Code 可以发现来自其他工具如 Claude Desktop 的服务器。
扩展：VS Code 扩展可以编程注册 MCP 服务器。
命令行：通过命令行安装MCP服务器，使用--加法-MCPVS Code 命令行选项。

了解更多关于将MCP服务器添加到VS Code的不同方法。

管理MCP服务器

你可以在VS Code中的扩展视图（⇧⌘X，Windows，Linux Ctrl+Shift+X））管理已安装的MCP服务器列表。

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

右键点击 MCP 服务器或选择齿轮图标，即可在服务器上执行不同的管理作。或者，从命令面板中运行 MCP： List Servers 命令，查看已配置的 MCP 服务器列表。然后你可以选择服务器并对其执行作。

提示

当你打开.vscode/mcp.json文件，VS Code 在编辑器中显示命令，用于直接从编辑器启动、停止或重启服务器。

MCP服务器配置，并用镜头管理服务器。

创建MCP安装URL。

VS Code 提供了一个从链接安装 MCP 服务器的 URL 处理程序：VScode：MCP/安装？{json-configuration}（内部人士：VScode-Insiders：mcp/install？{json-configuration}).

请以以下形式提供 JSON 服务器配置{\“name\”：\“server-name\”，\“command\”：...}然后对其执行JSON-stringify和URL编码。例如，使用以下逻辑创建安装URL：

// For Insiders, use `vscode-insiders` instead of `code`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;

该链接可以在浏览器中使用，或在命令行中打开，例如：XDG-开放$LINK在 Linux 上。

在扩展中注册一个MCP服务器

要在扩展中注册MCP服务器，您需要执行以下步骤：

在package.json你的延期档案。
在扩展代码中实现MCP服务器定义提供者，方法是使用vscode.lm.registerMcpServerDefinitionProviderAPI。

你可以从一个基本的示例开始，了解如何在VS Code扩展中注册MCP服务器。

1. 静态配置`package.json`

想要注册MCP服务器的扩展必须贡献贡献点。mcpServerDefinitionProviders延伸点在package.json其中身份证提供者的。这个身份证应该和实现中使用的匹配。

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

2. 实现提供者

要在扩展中注册MCP服务器，请使用vscode.lm.registerMcpServerDefinitionProviderAPI 用于为服务器提供 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: '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;
        }
    }));
}

排查和调试MCP服务器

VS Code 中的 MCP 开发模式

在开发MCP服务器时，可以通过添加一个开发者MCP服务器配置的密钥。这是一个具有两个属性的对象：

观看：文件块模式用于监控文件变化，从而重启MCP服务器。

调试：允许您在MCP服务器上设置调试器。目前，VS Code 支持调试 Node.js 和 Python MCP 服务器。

Node.js MCP 服务器

要调试Node.js MCP服务器，设置debug.type属性到节点.

{
  "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属性到调试，并可选择地设置debug.debugpyPath性质到路径调试如果模块未安装在默认的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：列表服务器，选择服务器，然后选择显示输出。

MCP服务器错误输出

最佳实践

命名规范以确保名字独特且具描述性
通过描述性错误消息实现正确的错误处理和验证
利用进度报告向用户介绍长期运营情况
保持工具作的聚焦和原子级，以避免复杂的交互
用描述清晰记录你的工具，帮助用户了解何时使用它们
通过提供默认值或清晰的错误信息，优雅地处理缺失的输入参数
为资源设置MIME类型，以确保在VS Code中正确处理不同内容类型
使用资源模板，允许用户在访问资源时提供输入参数
缓存资源内容以提升性能并减少不必要的网络请求
为抽样请求设置合理的令牌限制，以避免资源过度消耗
在使用抽样响应前，先验证其内容

命名惯例

以下推荐用于MCP服务器及其组件的命名规范：

组成部分	命名规范指南
工具名称	在MCP服务器内独一无二描述动作及其目标使用蛇形箱，结构为`{动词}_{名词}` 示例：`generate_report`,`fetch_data`,`analyze_code`
工具输入参数	描述参数的目的使用 camelCase 表示多字参数示例：`路径`,`queryString`,`用户ID`
资源名称	在MCP服务器内独一无二描述资源内容使用产权情况示例：`申请日志`,`数据库表`,`GitHub仓库`
资源模板参数	描述参数的目的使用 camelCase 表示多字参数示例：`名称`,`回收`,`文件类型`
提示名称	在MCP服务器内独一无二描述提示的预期用途使用 camelCase 表示多字参数示例：`生成ApiRoute`,`performSecurityReview`,`analyzeCodeQuality`
提示输入参数	描述参数的目的使用 camelCase 表示多字参数示例：`filePath`,`queryString`,`用户ID`

开始创建MCP服务器

VS Code 拥有开发自己 MCP 服务器所需的所有工具。而MCP服务器可以用任何能够处理的语言编写学生，MCP的官方SDK是一个不错的起点：

你可能也会觉得初学者MCP课程很有帮助，可以帮你开始搭建第一个MCP服务器。