MCP 开发者指南

Name: Visual Studio Code
Author: Microsoft

模型上下文协议 (Model Context Protocol, MCP) 是一种开放标准，它允许 AI 模型通过统一接口与外部工具和服务交互。Visual Studio Code 实现了完整的 MCP 规范，使你能够创建 MCP 服务器，为在 VS Code 中扩展 AI 代理功能提供工具、提示和资源。

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

重要

VS Code 中的 MCP 支持目前处于预览阶段。

为什么要使用 MCP 服务器？

实现 MCP 服务器以通过语言模型工具扩展 VS Code 中的聊天功能具有以下优点：

通过专业化、领域特定的工具扩展代理模式，这些工具会自动调用，作为响应用户提示的一部分。例如，启用数据库脚手架和查询，以动态地为大型语言模型（LLM）提供相关上下文。
适用于本地和远程场景的灵活部署选项。
在不同工具和平台之间重用你的 MCP 服务器。

在以下场景中，你可能需要考虑使用语言模型 API 实现语言模型工具：

你希望通过使用扩展 API 与 VS Code 深度集成。
你希望通过 Visual Studio Marketplace 分发你的工具和更新。

将 MCP 服务器添加到 VS Code

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

工作区配置：在工作区中的 .vscode/mcp.json 文件中指定服务器配置。
全局配置：在用户配置文件中全局定义服务器。
自动发现：VS Code 可以从 Claude Desktop 等其他工具中发现服务器。
扩展：VS Code 扩展可以通过编程方式注册 MCP 服务器。

此外，用户可以通过打开一个特殊 URL (vscode:mcp/install) 来触发 MCP 安装，该 URL 用于VS Code 网站上的 MCP 库。用户可以直接从“扩展”视图中的 MCP 视图访问该库。

最后，通过命令行选项 --add-mcp 从命令行安装 MCP 服务器。

管理 MCP 服务器

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

Screenshot showing the MCP servers in the Extensions view.

右键点击 MCP 服务器或选择齿轮图标以执行以下操作：

启动/停止/重启：启动、停止或重启 MCP 服务器。
断开账户：断开用于 MCP 服务器身份验证的账户。
显示输出：查看服务器日志以诊断问题。
显示配置：查看 MCP 服务器配置。
配置模型访问：配置 MCP 服务器可以访问哪些模型（采样）。
显示采样请求：查看 MCP 服务器发出的采样请求。
浏览资源：查看 MCP 服务器提供的资源。
卸载：从你的环境中卸载 MCP 服务器。

或者，从命令面板运行 MCP: 列出服务器 命令以查看已配置的 MCP 服务器列表。然后你可以选择一个服务器并对其执行操作。

提示

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

MCP server configuration with lenses to manage server.

MCP URL 处理器

VS Code 提供了一个 URL 处理器，用于从链接安装 MCP 服务器。要构建 URL，请按照提供给 --add-mcp 的相同格式构造一个 obj 对象，然后使用以下逻辑创建链接：

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

此链接可以在浏览器中使用，或在命令行上打开，例如在 Linux 上通过 xdg-open $LINK。

VS Code 支持的 MCP 功能

VS Code 支持以下 MCP 服务器传输方法：

标准输入/输出 (stdio)：将服务器作为本地进程运行，通过标准输入和输出进行通信。
流式 HTTP (http)：使用 HTTP POST 和 GET 与（远程）服务器通信。
服务器发送事件 (sse, 传统)：通过 HTTP 使用服务器发送事件支持与（远程）服务器通信。

VS Code 支持以下 MCP 功能：

工具：可以在代理模式中使用的可执行操作
提示：可重用的聊天提示模板，可选择带有参数，用户可以通过聊天中的斜杠命令 (/mcp.servername.promptname) 调用
资源：用户可以添加为聊天上下文或直接在 VS Code 中交互的数据和内容
授权：使用 OAuth 授权访问 MCP 服务器
采样 (预览)：使用用户配置的模型和订阅进行语言模型请求
启发：请求用户输入
工作区根目录：关于用户工作区结构的信息

有关完整的规范详细信息，请参阅 Model Context Protocol 文档。

工具

工具定义

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: 浏览资源 命令打开，或者通过 添加上下文 并选择 MCP 资源 附加到聊天请求。资源可以包含文本或二进制内容。

Screenshot that shows the MCP Resources Quick Pick.

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

Screenshot that shows the prompt dialog for an MCP prompt with input parameters.

注意

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

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

授权

VS Code 支持需要身份验证的 MCP 服务器，允许用户与代表其用户账户操作的 MCP 服务器进行交互以获取该服务。

授权规范将 MCP 服务器清晰地分离为资源服务器和授权服务器，允许开发者将身份验证委托给现有身份提供商，而不是从头开始构建自己的 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.

如果你的 MCP 服务器使用不同的授权服务器，VS Code 还支持动态客户端注册。然后用户也可以通过账户菜单查看他们的身份验证状态。要删除动态客户端注册，用户可以使用命令面板中的身份验证：移除动态身份验证提供商命令。

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

采样 (预览)

VS Code 为 MCP 服务器提供对采样的访问。这允许你的 MCP 服务器使用用户配置的模型和订阅进行语言模型请求。采样可用于在将大量数据发送到客户端之前进行总结或提取信息，或者在工具逻辑中实现更智能的代理决策。

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

Screenshot that shows the authorization prompt for an MCP server to access models.

用户可以使用命令面板中的 MCP: 列出服务器 > 配置模型访问 命令指定允许 MCP 服务器用于采样的模型。你可以在 MCP 服务器中指定 modelPreferences，以提供关于使用哪些模型进行采样的提示，VS Code 将在评估服务器偏好时从允许的模型中进行选择。

Screenshot that shows the Configure Model Access dialog for an MCP server.

用户可以使用命令面板中的 MCP: 列出服务器 > 显示采样请求 命令查看 MCP 服务器发出的采样请求。

工作区根目录

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

在扩展中注册 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 服务器时，你可以在 VS Code 中启用 MCP 开发模式。要启用开发模式，请将 dev 属性添加到你的 MCP 服务器配置中，并指定以下属性：

watch：用于监视文件更改并自动重启服务器的 glob 模式
debug：启动 MCP 服务器进程时附加的调试器（目前仅支持使用 node 或 python 启动的服务器）

以下示例展示了如何配置一个 Node.js MCP 服务器，该服务器监视 src 目录中 TypeScript 文件的更改并使用 Node.js 调试器：

{
  "servers": {
    "my-mcp-server": {
      "type": "stdio",
      "command": "node",
      "cwd": "${workspaceFolder}",
      "args": ["./build/index.js"],
      "dev": {
        "watch": "src/**/*.ts",
        "debug": { "type": "node" }
      }
    }
  }
}

MCP 输出日志

当 VS Code 遇到 MCP 服务器问题时，它会在“聊天”视图中显示错误指示器。

选择“聊天”视图中的错误通知，然后选择显示输出选项以查看服务器日志。或者，从命令面板运行MCP：列出服务器，选择服务器，然后选择显示输出。

MCP Server Error Output

最佳实践

命名约定以确保名称唯一且具有描述性
实现适当的错误处理和验证，并附带描述性错误消息
使用进度报告告知用户长时间运行的操作
保持工具操作的专注和原子性以避免复杂的交互
清晰地记录你的工具，并提供帮助用户理解何时使用它们的描述
优雅地处理缺失的输入参数，通过提供默认值或清晰的错误消息
为资源设置 MIME 类型以确保 VS Code 中不同内容类型的正确处理
使用资源模板允许用户在访问资源时提供输入参数
缓存资源内容以提高性能并减少不必要的网络请求
为采样请求设置合理的令牌限制以避免过多的资源使用
在使用采样响应之前验证采样响应

命名约定

建议 MCP 服务器及其组件采用以下命名约定：

组件	命名约定指南
工具名称	在 MCP 服务器内唯一描述操作和操作的目标使用蛇形命名法（snake_case），结构为 `{动词}_{名词}` 示例：`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 for Beginners 课程有助于你开始构建第一个 MCP 服务器。

07/09/2025