MCP 开发人员指南

Name: Visual Studio Code
Author: Microsoft

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

MCP 服务器提供 VS Code 中提供的三种工具之一，另外两种是内置工具和扩展提供的工具。详细了解工具类型。

本指南涵盖了使用 VS Code 和其他 MCP 客户端无缝运行的 MCP 服务器所需的所有知识。

提示

有关将 MCP 服务器用作最终用户的信息，请参阅在 VS Code 中使用 MCP 服务器。

为什么要使用 MCP 服务器？

在 VS Code 中使用 MCP 服务器扩展聊天功能并添加语言模型工具具有以下优势：

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

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

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

VS Code 支持的 MCP 功能

VS Code 支持以下 MCP 功能：

传输:
- 本地标准输入/输出 (stdio)
- 流式 HTTP (http)
- 服务器发送事件 (sse) - 向后兼容。
功能:
- 工具：用额外的工具扩展代理模式。
- 提示：将可重用的提示添加为聊天中的斜杠命令。
- 资源：提供用户可以添加为聊天上下文或直接在 VS Code 中交互的数据和内容。
- 引导：请求用户输入。
- 采样：使用用户配置的模型和订阅发出语言模型请求。
- 身份验证：使用 OAuth 授权访问 MCP 服务器。
- 服务器说明
- 根目录：提供有关用户工作区根文件夹的信息。

工具

工具定义

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 服务器（作为资源服务器）与授权服务器清晰地分开，使开发人员能够将身份验证委托给现有的身份提供商 (IdP)，而不是从头开始构建自己的 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.

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 时，用户将经历回退客户端凭据流程。

Screenshot that shows the authorization when DCR is not supported for a MCP server.

Screenshot that shows the authorization when Client ID for a MCP server is requested.

Screenshot that shows the authorization when Client Secret for a MCP server is requested.

注意

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 服务器提供用户工作区根文件夹信息。

图标

VS Code 支持 MCP 服务器、资源和工具上提供的图标。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 服务器：

直接从 Web 安装：在您的网站上使用特殊的 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 服务器列表。

Screenshot showing the MCP servers in the Extensions view.

右键单击 MCP 服务器或选择齿轮图标，以对服务器执行不同的管理操作。或者，从命令面板运行MCP：列出服务器命令以查看已配置的 MCP 服务器列表。然后，您可以选择一个服务器并对其执行操作。

提示

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

MCP server configuration with lenses to manage server.

创建 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 服务器，您需要执行以下步骤：

在扩展的 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：表示可以使用 Streamable 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 服务器时，您可以通过向 MCP 服务器配置添加 dev 键来启用 MCP 服务器的开发模式。这是一个具有两个属性的对象：

watch：一个文件 glob 模式，用于监视文件更改以重新启动 MCP 服务器。

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：列出服务器，选择服务器，然后选择显示输出。

MCP Server Error Output

最佳实践

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

命名约定

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

组件	命名约定指南
工具名称	在 MCP 服务器内唯一描述操作和操作的目标。使用 snake_case，结构为 `{verb}_{noun}`。示例：`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 入门教程，开始构建您的第一个 MCP 服务器。

01/08/2026