在 VS Code 中使用 MCP 服务器（预览版）

模型上下文协议 (MCP) 服务器使您能够通过额外的工具扩展 VS Code 中的聊天体验，这些工具用于连接到数据库、调用 API 或执行专业任务。模型上下文协议 (MCP) 是一种开放标准，它使 AI 模型能够通过统一接口与外部工具和服务交互。本文将指导您在 Visual Studio Code 中设置 MCP 服务器并使用代理模式下的工具。

先决条件

• 安装最新版 Visual Studio Code
• 访问 Copilot

什么是 MCP？

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

在 VS Code 中启用 MCP 支持

要在 VS Code 中启用 MCP 支持，请启用 chat.mcp.enabled 设置。

要在您的组织内集中启用或禁用 MCP 支持，请查看企业文档中的集中管理 VS Code 设置。

添加 MCP 服务器

您可以通过多种方式在 VS Code 中添加 MCP 服务器

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

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

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

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

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

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

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

2. 选择 Add Server 按钮以添加新服务器的模板。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 服务器类型并提供服务器信息。接下来，选择 Workspace Settings 以在您的工作区中创建 .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 命令，提供服务器信息，然后选择 User Settings 将服务器配置添加到您的用户设置中。

MCP 服务器的自动发现

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

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

配置格式

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

• "servers": {}

  包含 MCP 服务器列表，并遵循 Claude Desktop 的配置格式。

  将服务器名称指定为键，并将服务器配置作为值提供。VS Code 在 MCP 服务器列表中显示服务器名称。遵循以下服务器命名约定

  • 服务器名称使用驼峰式命名，例如 "uiTesting"。
  • 避免使用空格或特殊字符。
  • 为每个服务器使用唯一名称以避免冲突。
  • 使用描述性名称来反映服务器的功能或品牌，例如 "github" 或 "database"。

  在服务器配置中提供以下字段。您可以在服务器配置中使用预定义变量，例如引用工作区文件夹 (${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"

  `sse` 或 `http` 的服务器配置

  字段	描述	示例
  type	服务器连接类型。VS Code 首先尝试可流式 HTTP 传输，如果 HTTP 不支持则回退到 SSE。	"sse", "http"
  url	服务器的 URL。	"http://localhost:3000"
  headers	服务器的 HTTP 头。	{"API_KEY": "${input:api-key}"}

• "inputs": []

  允许您为配置值定义自定义占位符，以避免在服务器配置中硬编码敏感信息，例如 API 密钥或密码。

  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）），然后从下拉菜单中选择代理模式。

   

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

   （可选）选择或取消选择您要使用的工具。您可以通过在搜索框中键入来搜索工具。

   

   提示

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

3. 选择添加上下文 > MCP 资源，将 MCP 服务器中的资源添加到您的聊天上下文中。

   例如，数据库 MCP 服务器可能提供对数据库表的访问，或者文件系统 MCP 服务器可能提供对文件和目录的访问。

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

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

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

   

5. （可选）在运行工具之前验证和编辑工具输入参数。

   

使用 MCP 资源

除了工具之外，MCP 服务器还可以提供您可以在聊天提示中用作上下文的资源。例如，文件系统 MCP 服务器可能提供对文件和目录的访问，或者数据库 MCP 服务器可能提供对数据库表的访问。

要将 MCP 服务器中的资源添加到您的聊天提示中

1. 在聊天视图中，选择添加上下文 > MCP 资源

2. 从列表中选择资源类型并提供可选的资源输入参数。

   

要查看 MCP 服务器的可用资源列表，请使用 MCP: Browse Resources 命令或使用 MCP: List Servers > Browse Resources 命令来查看特定服务器的资源。

MCP 工具可以作为其响应的一部分返回资源。您可以使用保存按钮或将资源拖放到资源管理器视图中来查看或保存这些资源到您的工作区。

使用 MCP 提示

MCP 服务器可以为常见任务提供预配置的提示，这样您就不必输入详细的聊天提示。您可以通过在聊天输入框中输入 / 后跟提示名称（格式为 mcp.servername.promptname）来直接调用这些提示。可选地，提示可能会要求您提供额外的输入参数。

在工具集中分组相关工具

随着您添加更多 MCP 服务器，工具列表可能会变得很长。这使得管理单个工具变得繁琐，例如当您想要定义一个可重用提示文件或自定义聊天模式时。

为了帮助您管理工具，您可以将相关工具分组到一个工具集中。工具集是单个工具的集合，您可以将其作为一个整体来引用。工具集可以包含内置工具、MCP 工具或扩展提供的工具。

了解更多关于如何在 VS Code 中创建和使用工具集的信息。

管理 MCP 服务器

从命令面板运行 MCP: List Servers 命令以查看已配置的 MCP 服务器列表。然后您可以选择一个服务器并对其执行以下操作

• 启动：如果 MCP 服务器尚未运行，则启动它。
• 停止：如果 MCP 服务器正在运行，则停止它。
• 重启：重启 MCP 服务器。
• 显示输出：查看服务器日志以诊断问题。
• 显示配置：在编辑器中查看服务器配置。
• 配置模型访问：配置 MCP 服务器可以访问哪些模型（采样）。
• 浏览资源：查看 MCP 服务器提供的资源。

命令行配置

您还可以使用 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，请以与提供给 --add-mcp 相同的格式构建一个 obj 对象，然后使用以下逻辑创建链接

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

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

MCP 服务器故障排除和调试

MCP 输出日志

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

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

调试 MCP 服务器

您可以通过向 MCP 服务器配置添加 dev 键来启用 MCP 服务器的开发模式。这是一个包含两个属性的对象

• watch：一个文件 glob 模式，用于监视文件更改，这将重启 MCP 服务器。
• debug：使您能够使用 MCP 服务器设置调试器。

{
  "servers": {
    "gistpad": {
      "command": "node",
      "args": ["build/index.js"],
     "dev": {
       "watch": "build/**/*.js",
       "debug": { "type": "node" }
     },

创建 MCP 服务器

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

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

常见问题

我能控制使用哪些 MCP 工具吗？

是的，您有多种选项来控制哪些工具处于活动状态

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

使用 Docker 时 MCP 服务器未启动

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

相关资源

• 模型上下文协议文档
• 模型上下文协议服务器仓库
• 在 Visual Studio Code 中使用代理模式