在 VS Code 中尝试

在 VS Code 中使用 MCP 服务器(预览)

模型上下文协议 (MCP) 是一个开放标准,它使 AI 模型能够通过统一接口与外部工具和服务交互。在 VS Code 中,MCP 支持通过允许您将任何 MCP 兼容服务器连接到您的代理编码工作流来增强 GitHub Copilot 的代理模式。本文指导您在 Visual Studio Code 中设置 MCP 服务器以及在代理模式下使用工具。

注意

VS Code 中代理模式下的 MCP 支持目前处于预览阶段。

先决条件

什么是 MCP?

模型上下文协议 (MCP) 为 AI 模型提供了一种标准化方式来发现外部工具、应用程序和数据源并与之交互。当您在 VS Code 中使用代理模式向语言模型输入聊天提示时,模型可以调用各种工具来执行文件操作、访问数据库或调用 API 等任务,以响应您的请求。

MCP 遵循客户端-服务器架构

  • MCP 客户端(如 VS Code)连接到 MCP 服务器,并代表 AI 模型请求执行操作
  • MCP 服务器提供一个或多个工具,这些工具通过明确定义的接口公开特定功能
  • 模型上下文协议 (MCP) 定义了客户端和服务器之间通信的消息格式,包括工具发现、调用和响应处理

例如,文件系统 MCP 服务器可以提供用于读取、写入或搜索文件和目录的工具。GitHub 的 MCP 服务器提供列出存储库、创建拉取请求或管理问题的工具。MCP 服务器可以在您的计算机上本地运行或远程托管,VS Code 支持这两种配置。

通过标准化这种交互,MCP 消除了每个 AI 模型与每个工具之间的自定义集成需求。这使您只需将新的 MCP 服务器添加到您的工作区即可扩展 AI 助手的功能。详细了解 模型上下文协议规范

支持的 MCP 功能

VS Code 支持本地标准输入/输出 (stdio)、服务器发送事件 (sse) 和流式 HTTP (http) 作为 MCP 服务器传输方式。目前在 三种基本类型 (toolspromptsresources) 中,服务器只能向 Copilot 的代理模式提供 tools。工具列表和描述可以使用 列表更改 事件动态更新。VS Code 使用 roots (规范) 向服务器提供当前工作区文件夹。

查找 MCP 服务器

MCP 的官方服务器存储库是参考、官方和社区贡献服务器的绝佳起点,这些服务器展示了 MCP 的多功能性。您可以探索各种功能的服务器,例如文件系统操作、数据库交互和 Web 服务。

MCP 仍是一个相对较新的标准,生态系统正在快速发展。随着越来越多的开发人员采用 MCP,您可以期望看到越来越多的服务器和工具可用于与您的项目集成。

在 VS Code 中启用 MCP 支持

注意

VS Code 中代理模式下的 MCP 支持目前处于预览阶段。

MCP 支持从 VS Code 1.99 版本开始可用。要在 VS Code 中启用 MCP 支持,请启用 chat.mcp.enabled 设置。此设置默认启用。

添加 MCP 服务器

您有多种选择在 VS Code 中添加 MCP 服务器

  • 工作区设置:在您的工作区中添加一个 .vscode/mcp.json 文件,用于配置工作区的 MCP 服务器并与团队成员共享配置。
  • 用户设置:在您的用户设置中指定服务器,以在所有工作区中启用 MCP 服务器。
  • 自动发现:启用自动发现其他工具中定义的 MCP 服务器,例如 Claude Desktop。
注意

MCP 服务器可以在您的计算机上运行任意代码。仅添加来自受信任来源的服务器,并在启动之前查看发布者和服务器配置。

要查看和管理已配置的 MCP 服务器列表,请从命令面板运行 MCP: List Servers 命令。

添加 MCP 服务器后,您可以在代理模式下使用它提供的工具

将 MCP 服务器添加到您的工作区

要为特定工作区配置 MCP 服务器,您可以在工作区文件夹中创建 .vscode/mcp.json 文件。这使您可以与项目团队成员共享服务器配置。

重要事项

确保使用输入变量或环境文件,避免硬编码 API 密钥和其他凭据等敏感信息。

将 MCP 服务器添加到您的工作区

  1. 在您的工作区中创建 .vscode/mcp.json 文件。

  2. 选择 添加服务器 按钮以添加新服务器模板。VS Code 为 MCP 服务器配置文件提供 IntelliSense。

    以下示例展示了如何配置 Perplexity MCP 服务器,其中 VS Code 在服务器启动时提示您输入 API 密钥。详细了解配置格式

    {
      // 💡 Inputs are prompted on first server start, then stored securely by VS Code.
      "inputs": [
        {
          "type": "promptString",
          "id": "perplexity-key",
          "description": "Perplexity API Key",
          "password": true
        }
      ],
      "servers": {
        // https://github.com/ppl-ai/modelcontextprotocol/
        "Perplexity": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "server-perplexity-ask"],
          "env": {
            "PERPLEXITY_API_KEY": "${input:perplexity-key}"
          }
        }
      }
    }
    
  3. 或者,从命令面板运行 MCP: Add Server 命令,选择要添加的 MCP 服务器类型并提供服务器信息。接下来,如果您的工作区中尚不存在 .vscode/mcp.json 文件,请选择 工作区设置 来创建它。

将 MCP 服务器添加到您的用户设置

要为所有工作区配置 MCP 服务器,您可以将服务器配置添加到您的用户设置中。这使您可以在多个项目中重用相同的服务器配置。

mcp VS Code 用户设置中指定服务器,以在所有工作区中启用 MCP 服务器。

// settings.json
{
  "mcp": {
    "servers": {
      "my-mcp-server": {
        "type": "stdio",
        "command": "my-command",
        "args": []
      }
    }
  }
}

或者,从命令面板使用 MCP: Add Server 命令,提供服务器信息,然后选择 用户设置 将服务器配置添加到您的用户设置。

MCP 服务器的自动发现

VS Code 可以自动检测和重用您在其他工具(例如 Claude Desktop)中定义的 MCP 服务器。

使用 chat.mcp.discovery.enabled 设置启用自动发现。

配置格式

使用以下 JSON 配置格式定义 MCP 服务器。

  • "servers": {} 字段包含 MCP 服务器列表,并遵循 Claude Desktop 的配置格式。

    将服务器名称指定为键,并提供服务器配置作为值。VS Code 在 MCP 服务器列表中显示服务器名称。

    在服务器配置中提供以下字段。您可以在服务器配置中使用预定义变量,例如引用工作区文件夹 (${workspaceFolder})。

    使用 stdio 连接

    字段 说明 示例
    type 服务器连接类型。 "stdio"
    command 启动服务器可执行文件的命令。该命令需要在您的系统路径中可用或包含其完整路径。
    如果您使用 docker,请勿使用 detach 选项。
    "npx""node""python""docker"
    args 传递给命令的参数数组。 ["server.py", "--port", "3000"]
    env 服务器的环境变量。 {"API_KEY": "${input:api-key}"}
    envFile 从中加载其他环境变量的 .env 文件的路径。 "${workspaceFolder}/.env"

    使用 ssehttp 连接

    字段 说明 示例
    type 服务器连接类型。VS Code 首先尝试流式 HTTP 传输,如果不支持 HTTP,则回退到 SSE。 "sse""http"
    url 服务器的 URL。 "http://localhost:3000"
    headers 服务器的 HTTP 头部。 {"API_KEY": "${input:api-key}"}
  • "inputs": [] 字段允许您为配置值定义自定义占位符,避免硬编码敏感信息。

    VS Code 在服务器首次启动时提示您输入这些值,并安全地存储它们以供后续使用。为避免显示输入的值,请将 password 字段设置为 true

    详细了解如何在 VS Code 中配置输入变量

配置示例

以下代码片段展示了一个示例 MCP 服务器配置,该配置指定了三个服务器并为 API 密钥定义了一个输入占位符。

// Example .vscode/mcp.json
{
  // 💡 Inputs will be prompted on first server start,
  //    then stored securely by VS Code.
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "Perplexity API Key",
      "password": true
    }
  ],
  "servers": {
    // https://github.com/ppl-ai/modelcontextprotocol/
    "Perplexity": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "PERPLEXITY_API_KEY", "mcp/perplexity-ask"],
      "env": {
        "PERPLEXITY_API_KEY": "${input:perplexity-key}"
      }
    },
    // https://github.com/modelcontextprotocol/servers/tree/main/src/fetch
    "fetch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "my-remote-server": {
      "type": "sse",
      "url": "http://api.contoso.com/sse",
      "headers": { "VERSION": "1.2" }
    }
  }
}

在代理模式下使用 MCP 工具

添加 MCP 服务器后,您可以在代理模式下使用它提供的工具。要在代理模式下使用 MCP 工具

  1. 打开聊天视图 (⌃⌘I (Windows, Linux Ctrl+Alt+I)),然后从下拉列表中选择代理模式。

    Agent mode dropdown option

  2. 选择工具按钮查看可用工具列表。

    (可选)选择或取消选择您想要使用的工具。您可以在搜索框中输入来搜索工具。

    MCP tools list

    提示

    您也可以通过键入 # 后跟工具名称来直接在提示中引用工具。您可以在所有聊天模式(提问、编辑和代理模式)中执行此操作。

  3. 现在您可以在聊天输入框中输入提示,并注意工具如何根据需要自动调用。

    默认情况下,当调用工具时,您需要在运行之前确认该操作。这是因为工具可能在您的计算机上本地运行,并可能执行修改文件或数据的操作。

    使用继续按钮下拉选项,以自动确认当前会话、工作区或所有未来调用的特定工具。

    MCP Tool Confirmation

  4. (可选)在运行工具之前验证和编辑工具输入参数。

    选择工具名称旁边的箭头以查看其详细信息和输入参数。您可以在运行工具之前编辑输入参数。

    MCP Tool Input Parameters

管理工具

从命令面板运行 MCP: List Servers 命令以查看已配置的 MCP 服务器列表。

MCP server list

选择服务器后,您可以启动、停止或重新启动服务器。您还可以查看服务器配置和服务器日志以诊断问题。

提示

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

MCP server configuration with lenses to manage server.

命令行配置

您还可以使用 VS Code 命令行界面将 MCP 服务器添加到您的用户配置文件或工作区。

要将 MCP 服务器添加到您的用户配置文件,请使用 --add-mcp 命令行选项,并以 {\"name\":\"server-name\",\"command\":...} 的形式提供 JSON 服务器配置。

code --add-mcp "{\"name\":\"my-server\",\"command\": \"uvx\",\"args\": [\"mcp-server-fetch\"]}"

URL 处理程序

VS Code 还包括一个 URL 处理程序,您可以使用它来安装 MCP 服务器。要构成 URL,请构建一个 obj 对象,其格式与提供给 --add-mcp 的格式相同,然后使用以下逻辑创建链接

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

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

故障排除

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

MCP Server Error

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

MCP Server Error Output

创建 MCP 服务器

VS Code 拥有开发您自己的 MCP 服务器所需的所有工具。虽然 MCP 服务器可以使用任何可以处理 stdout 的语言编写,但 MCP 的官方 SDK 是一个不错的起点

常见问题

我能否控制使用哪些 MCP 工具?

是的,您有几种选项可以控制哪些工具处于活动状态

  • 在代理模式下时,选择聊天视图中的工具按钮,并根据需要切换特定工具的开启/关闭。
  • 使用添加上下文按钮或键入 #,将特定工具添加到您的提示中。
  • 对于更高级的控制,您可以使用 .github/copilot-instructions.md 来微调工具的使用。

使用 Docker 时 MCP 服务器无法启动

验证命令参数是否正确,并且容器未在分离模式(-d 选项)下运行。您还可以检查 MCP 服务器输出中是否有任何错误消息(请参阅故障排除)。