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 中的聊天功能具有以下优势：

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

在以下场景中，您可以考虑使用 语言模型 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 提供了更大的灵活性，可以为每个 MCP 服务器创建静态客户端 ID 或特定的客户端 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 服务器：

• 从 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 服务器列表。

右键单击 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 在您的扩展代码中实现 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 服务器。

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 模式或 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 属性为该模块的路径。

  {
    "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 服务器列表
• 模型上下文协议文档