MCP 开发者指南

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

MCP服务器提供VS Code中可用的三种类型工具之一，与内置工具和扩展贡献的工具一起使用。了解更多关于工具类型的信息。

本指南涵盖了您需要了解的所有信息，以构建与 VS Code 和其他 MCP 客户端无缝集成的 MCP 服务器。

为什么使用MCP服务器？

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

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

您可能需要在以下情况下考虑实现语言模型工具与 语言模型 API：

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

VS Code 支持的 MCP 功能

VS Code 支持以下 MCP 功能：

• 传输:

  • 本地标准输入/输出 (标准输入输出)
  • 可流式传输的HTTP (对不起，我无法处理你提供的内容。)
  • 服务器发送事件 (上海证券交易所) - 遗产支持。

• 功能:

  • 工具：扩展代理模式的额外工具
  • 提示：在聊天中添加可重复使用的提示作为斜线命令
  • 资源：提供数据和内容，用户可以将其添加为聊天上下文或直接在 VS Code 中与其互动
  • 需求获取：请求用户输入
  • 采样：使用用户配置的模型和订阅进行语言模型请求
  • 认证：使用OAuth授权访问MCP服务器
  • 服务器指令
  • 根目录：提供有关用户工作区根文件夹的信息
  • MCP 应用程序：从工具中返回交互式用户界面组件

工具

工具定义

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

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

动态工具发现

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

工具注释

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

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

资源

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

当您定义一个MCP资源时，资源名称会显示在MCP资源快速选择中。资源可以通过MCP：浏览资源命令打开，或者附加到聊天请求中，使用添加上下文并选择MCP资源。资源可以包含文本或二进制内容。

VS Code 支持资源更新，使用户能够实时在编辑器中看到资源内容的更改。

资源模板

VS Code 还支持资源模板，使用户在引用资源时可以提供输入参数。例如，一个数据库查询工具可能会询问数据库表名。

当使用模板访问资源时，系统会提示用户输入所需的参数。您可以提供补全建议以建议参数的值。

提示

Prompts 是可重复使用的聊天提示模板，用户可以通过使用斜线命令在聊天中调用。mcp.服务器名称.提示名称提示可以用于通过突出显示各种工具或提供内置的复杂工作流程来引导用户进入您的服务器，这些工作流程能够适应用户的本地上下文和服务。

如果你定义完成来建议提示输入参数的值，那么 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服务器作为资源服务器与授权服务器分离，使开发人员可以将身份验证委托给现有的身份提供者（IdPs），而不是从头开始构建自己的OAuth实现。

VS Code 对 GitHub 和 Microsoft Entra 提供内置的认证支持。如果您的 MCP 服务器实现了最新的规范并使用 GitHub 或 Microsoft Entra 作为授权服务器，用户可以通过 Accounts 菜单 > 管理受信任的 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. 身份提供者必须支持DCR或客户端凭证中的一个
3. 重定向URL列表必须包括这些URL：http://127.0.0.1:33418和https://vscode.dev/redirect

当MCP服务器不支持DCR时，用户将通过回退客户端-凭证流程：

采样

VS Code 提供了对 采样 的访问，用于 MCP 服务器。这使得您的 MCP 服务器可以使用用户配置的模型和订阅来对语言模型请求进行操作。例如，使用采样对大型数据集进行总结，提取信息以发送给客户端，或在工具中实现代理决策逻辑。

第一次执行采样请求时，MCP服务器会提示用户授权服务器访问他们的模型。

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

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

工作区根

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

MCP 应用程序

MCP 应用程序使工具能够返回在聊天中以交互式用户界面组件渲染的输出，而不是仅限于文本输出。这对于拖放列表排序、可视化、表单和多步骤工作流程等场景非常有用。

Architecture

MCP 应用程序使用工具 + 用户界面资源模式：

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

软件开发工具包

使用@模型上下文协议/扩展应用用于构建MCP应用程序的包。SDK提供：

• 应用程序 class：与主机通信的主要界面

  • 连接(): 与 VS Code 建立连接
  • 调用服务器工具(name, args)调用原MCP服务器上的工具
  • sendMessage(content)发送消息到聊天输入框
  • 更新模型上下文(上下文)提供未来对话的背景
  • 打开链接(url)请求在浏览器中打开一个URL
  • 发送日志(级别, 消息)发送调试日志（不添加到对话中）

• 通知处理程序：设置这些以从 VS Code 接收事件

  • 工具输入: 接收完整的工具参数
  • 工具输入部分接收流部分参数
  • 工具结果: 接收工具执行结果
  • 工具已取消处理工具取消
  • 在主机上下文更改时: 响应主题或区域的变化
  • 在销毁时卸载前清理

VS Code 行为和限制

安全

MCP 应用程序在带有内容安全策略 (CSP) 的沙盒 iframe 中运行。当定义一个 UI 资源时，声明您的应用程序需要访问的域：

• 连接域: 取得/XHR请求的域名
• 资源域: 图片、字体和其他资源的域名
• 框架域可以嵌入到 iframes 中的域名

了解更多

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

图标

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

• 使用HTTP或SSE传输的MCP服务器可能会从与MCP服务器相同的权威机构提供图像。例如，一个配置在https://example.com/mcp可以提供图像从example.com输入：.
• 使用stdio传输的MCP服务器可能会从文件系统中提供图像文件://统一资源标识符 (URIs)。
• 任何MCP服务器都可以将图像嵌入为以数据URI开头的数据数据:输入：.

将MCP服务器添加到VS Code

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

• 直接从网络安装：使用特殊的MCP安装网址vscode:mcp/安装) 在你的网站上。
• 工作区配置：在 中指定服务器配置.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: List Servers命令以查看配置的MCP服务器列表。然后您可以选择一个服务器并对其执行操作。

创建一个 MCP 安装网址

VS Code 提供了一个 URL 处理程序，用于通过链接安装 MCP 服务器：vscode:mcp/install?{json-configuration}（内部人士：vscode-insiders:mcp/安装?{json-配置})。

提供JSON服务器配置表单{"name":"服务器名称","command":...}然后对它进行JSON字符串化和URL编码。例如，使用以下逻辑来创建安装URL：

// 对于Insiders，使用`vscode-insiders`而不是`code`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;

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

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

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

1. 定义MCP服务器定义提供者在package.json您的扩展文件。
2. 在你的扩展代码中使用 实现 MCP 服务器定义提供者vscode.lm.registerMcpServerDefinitionProvider应用程序编程接口。

你可以开始使用一个基本的在 VS Code 扩展中注册 MCP 服务器的示例。

1. 静态配置在package.json

想要注册MCP服务器的扩展必须贡献contributes.mcpServerDefinitionProviders扩展点在package.json与id提供者的。这id应该与实现中使用的相同。

{
    ...
    "contributes": {
        "mcpServerDefinitionProviders": [
            {
                "id": "exampleProvider",
                "label": "示例 MCP 服务器提供者"
            }
        ]
    }
    ...
}

2. 实施提供商

要将MCP服务器注册到您的扩展中，请使用vscode.lm.registerMcpServerDefinitionProvider 提供服务器的 MCP配置 的API。该API接受一个 提供者ID字符串和一个Mcp服务器定义提供者对象。

该Mcp服务器定义提供者对象有三个属性：

• onDidChangeMcpServerDefinitions: 事件触发器，当MCP服务器配置更改时。
• 提供Mcp服务器定义: 返回一个MCP服务器配置数组的函数 (vscode.McpServerDefinition[])。
• 解析Mcp服务器定义: 编辑器调用的函数，当需要启动MCP服务器时。使用此函数执行可能需要用户交互的附加操作，例如身份验证。

一个Mcp服务器定义对象可以是以下类型之一：

• 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: '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 server;
        }
    }));
}

排除故障和调试MCP服务器

VS Code 中的 MCP 开发模式

在开发MCP服务器时，你可以通过添加一个开发模式来启用MCP服务器的开发模式开发MCP服务器配置的关键。这是一个具有两个属性的对象：

• 手表: 一个文件通配符模式，用于监控文件变化，这将重启MCP服务器。

• 调试: 使您能够设置与MCP服务器的调试器。目前，VS Code支持调试Node.js和Python MCP服务器。

  Node.js MCP 服务器

  要调试Node.js MCP服务器，请设置调试类型属性到节点输入：.

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

  Python MCP 服务器

  To debug a Python MCP server, set the debug.type property to debugpy, and optionally set the debug.debugpyPath property to the path of the debugpy module if it is not installed in the default Python environment.

  {
    "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 服务器发生问题时，它会在 Chat 视图中显示一个错误指示器。

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

最佳实践

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

命名约定

以下是推荐的MCP服务器及其组件的命名约定：

开始创建一个MCP服务器

VS Code 有你开发自己的 MCP 服务器所需的所有工具。虽然 MCP 服务器可以用任何可以处理标准输出, MCP 的官方 SDK 是个不错的起点：

• TypeScript SDK
• Python 软件开发工具包
• Java SDK
• Kotlin SDK
• C# 软件开发工具包

你可能还会发现初学者MCP课程对开始构建你的第一个MCP服务器很有帮助。

相关内容

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