MCP 开发者指南

模型上下文协议 (Model Context Protocol, MCP) 是一项开放标准，旨在使 AI 模型能够通过统一接口与外部工具和服务进行交互。Visual Studio Code 实现了完整的 MCP 规范，使您能够创建 MCP 服务器，从而提供工具、提示词 (prompts) 和资源，以扩展 VS Code 中 AI 代理的能力。

MCP 服务器提供 VS Code 中三种可用工具类型中的一种，其他两种为内置工具和扩展贡献工具。了解有关 工具类型 的更多信息。

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

为什么要使用 MCP 服务器？

通过实现 MCP 服务器来使用语言模型工具扩展 VS Code 聊天功能，具有以下优势：

• 扩展代理模式 (Agent mode)：利用特定领域的专业工具，在响应用户提示词时自动调用这些工具。例如，启用数据库脚手架和查询功能，从而动态地为大语言模型 (LLM) 提供相关上下文。
• 灵活的部署选项：适用于本地和远程场景。
• 重用性：在不同的工具和平台之间重复使用您的 MCP 服务器。

在以下场景中，您可以考虑使用 语言模型 API (Language Model API) 来实现语言模型工具：

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

VS Code 支持的 MCP 特性

VS Code 支持以下 MCP 功能：

• 传输协议:

  • 本地标准输入/输出 (stdio)
  • 流式 HTTP (http)
  • 服务器发送事件 (sse) - 旧版支持。

• 功能:

  • 工具：使用额外工具扩展 代理模式
  • 提示词：在聊天中以斜杠命令形式添加可重用的提示词
  • 资源：提供用户可作为聊天上下文添加或在 VS Code 中直接交互的数据和内容
  • 启发 (Elicitation)：请求用户输入
  • 采样 (Sampling)：使用用户配置的模型和订阅进行语言模型请求
  • 身份验证：使用 OAuth 授权访问 MCP 服务器
  • 服务器指令
  • 根目录 (Roots)：提供有关用户工作区根文件夹的信息
  • MCP 应用：从工具返回交互式 UI 组件

工具

工具定义

VS Code 在代理模式下支持 MCP 工具，根据任务需要调用它们。用户可以通过工具选择器启用和配置它们。工具描述会显示在工具选择器中（连同工具名称一起），并在执行工具前的确认对话框中显示。

用户可以在工具确认对话框中编辑模型生成的输入参数。所有未标记 readOnlyHint 注解的工具都会显示确认对话框。

动态工具发现

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

工具注解

要提供有关工具行为的额外元数据，您可以使用 工具注解：

• title：工具的可读标题，在调用工具时显示在“聊天”视图中。
• readOnlyHint：可选提示，指示该工具为只读。VS Code 不会请求确认即可运行只读工具。

资源

资源使您能够以结构化的方式向用户提供数据和内容。用户可以直接在 VS Code 中访问资源，或将其用作聊天提示词中的上下文。例如，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!` }
      }
    ]
  })
);

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

授权

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

授权规范 将作为资源服务器的 MCP 服务器与授权服务器清晰地分离开来，使开发者能够将身份验证委托给现有的身份提供商 (IdP)，而无需从零开始构建自己的 OAuth 实现。

VS Code 内置了对 GitHub 和 Microsoft Entra 的身份验证支持。如果您的 MCP 服务器实现了最新规范并使用 GitHub 或 Microsoft Entra 作为授权服务器，用户可以通过该账户的 账户菜单 > 管理受信任的 MCP 服务器 操作来管理哪些 MCP 服务器有权访问其账户。

VS Code 支持使用 OAuth 2.1 和 2.0 标准对 GitHub 和 Microsoft Entra 之外的 IdP 进行授权。VS Code 首先启动 动态客户端注册 (DCR) 握手，如果 IdP 不支持 DCR，则回退到客户端凭据工作流。这为各个 IdP 创建静态客户端 ID 或为每个 MCP 服务器创建特定的客户端 ID-密钥对提供了更大的灵活性。

用户还可以通过 账户菜单 查看其身份验证状态。要删除动态客户端注册，用户可以使用命令面板中的 身份验证: 删除动态身份验证提供程序 命令。

以下是确保您的 MCP 服务器和 VS Code 的 OAuth 工作流能够正常工作的清单：

1. MCP 服务器定义了 MCP 授权规范。
2. IdP 必须支持 DCR 或客户端凭据。
3. 重定向 URL 列表必须包含这些 URL：http://127.0.0.1:33418 和 https://vscode.dev/redirect

当 MCP 服务器不支持 DCR 时，用户将通过回退客户端凭据流。

采样 (Sampling)

VS Code 为 MCP 服务器提供了 采样 访问权限。这允许您的 MCP 服务器使用用户配置的模型和订阅进行语言模型请求。例如，使用采样来汇总大型数据集、在发送给客户端之前提取信息，或在工具中实现代理决策逻辑。

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

当使用特定模型进行采样请求时，请考虑用户可以通过命令面板中的 MCP: 列出服务器 > 配置模型访问 命令限制 MCP 服务器可以使用的模型。当您在 MCP 服务器中指定 modelPreferences 以提供有关使用哪些模型进行采样的提示时，VS Code 将从允许的模型中进行选择。

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

工作区根目录

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

MCP 应用

MCP 应用使工具能够返回交互式 UI 组件，这些组件会在聊天中内联呈现，而不是仅输出文本。这对于拖放列表重排序、可视化、表单和多步骤工作流等场景非常有用。

架构

MCP 应用使用“工具 + UI 资源”模式。

1. 定义一个返回指向 UI 资源的 _meta.ui.resourceUri 的工具。
2. 创建一个使用 ui:// URI 方案和 MIME 类型 text/html;profile=mcp-app 的 UI 资源。
3. HTML 资源在沙盒 iframe 中运行，并使用 MCP 应用 SDK 与 VS Code 进行通信。

SDK

使用 @modelcontextprotocol/ext-apps 包来构建 MCP 应用。该 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 行为和限制

安全性

MCP 应用在受内容安全策略 (CSP) 强制执行的沙盒 iframe 中运行。定义 UI 资源时，请声明您的应用需要访问的域：

• connectDomains：用于 fetch/XHR 请求的域。
• resourceDomains：用于图像、字体和其他资源的域。
• frameDomains：可以嵌入到 iframe 中的域。

了解更多

• MCP 应用规范
• MCP Apps SDK 和示例
• MCP 应用公告博客文章

图标

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

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

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

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

1. 在您的扩展的 package.json 文件中定义 MCP 服务器定义提供程序。
2. 通过使用 vscode.lm.registerMcpServerDefinitionProvider API 在您的扩展代码中实现该提供程序。

您可以参考 如何在 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：表示通过运行本地进程并在其标准输入和标准输出流上操作而可用的 MCP 服务器。
• vscode.McpHttpServerDefinition：表示使用流式 HTTP 传输可用的 MCP 服务器。

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 键来启用 开发模式。这是一个包含两个属性的对象：

• 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，如果未安装在默认 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: 列出服务器，选择服务器，然后选择 显示输出。

最佳实践

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

命名约定

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

开始创建 MCP 服务器

VS Code 拥有开发自己的 MCP 服务器所需的所有工具。虽然 MCP 服务器可以用任何能够处理 stdout 的语言编写，但 MCP 的官方 SDK 是一个很好的起点：

• TypeScript SDK
• Python SDK
• Java SDK
• Kotlin SDK
• C# SDK

您可能会发现 MCP 入门课程 对构建您的第一个 MCP 服务器很有帮助。

相关内容

• 贡献语言模型工具
• 在代理模式中使用 MCP 工具
• VS Code 精选的 MCP 服务器列表
• 模型上下文协议文档