在 VS Code 中使用 MCP 服务器
模型上下文协议 (MCP) 服务器可让您通过额外的工具(用于连接数据库、调用 API 或执行专门任务)扩展在 VS Code 中的聊天体验。模型上下文协议 (MCP) 是一种开放标准,它使 AI 模型能够通过统一接口与外部工具和服务进行交互。本文将指导您如何在 Visual Studio Code 中设置 MCP 服务器并以代理模式使用工具。
先决条件
- 安装最新版本的 Visual Studio Code
- 访问 Copilot
什么是 MCP?
模型上下文协议 (MCP) 提供了一种标准化方式,让 AI 模型能够发现并与外部工具、应用程序和数据源进行交互。当您在 VS Code 中以代理模式向语言模型输入聊天提示时,模型可以调用各种工具来执行任务,例如文件操作、访问数据库或根据您的请求调用 API。
MCP 如何工作?
MCP 遵循客户端-服务器架构
- MCP 客户端(如 VS Code)连接到 MCP 服务器并代表 AI 模型请求操作
- MCP 服务器提供一个或多个工具,通过定义明确的接口公开特定功能
- 模型上下文协议 (MCP) 定义了客户端和服务器之间通信的消息格式,包括工具发现、调用和响应处理
例如,文件系统 MCP 服务器可以提供用于读取、写入或搜索文件和目录的工具。GitHub 的 MCP 服务器提供用于列出存储库、创建拉取请求或管理问题的工具。MCP 服务器可以在本地机器上运行,也可以远程托管,VS Code 支持这两种配置。
通过标准化这种交互,MCP 消除了每个 AI 模型和每个工具之间进行自定义集成的需要。这使您可以通过简单地向工作区添加新的 MCP 服务器来扩展 AI 助手的功能。了解更多关于模型上下文协议规范的信息。
VS Code 中支持的 MCP 功能
VS Code 支持以下 MCP 功能
查找 MCP 服务器
VS Code 网站上精心策划的 MCP 服务器列表是一个很好的起点。从不同类别中选择并直接在 VS Code 中安装 MCP 服务器。
MCP 的官方服务器存储库提供了官方和社区贡献的服务器,展示了 MCP 的多功能性。您可以探索各种功能的服务器,例如文件系统操作、数据库交互和 Web 服务。
MCP 仍然是一个相对较新的标准,生态系统正在迅速发展。随着越来越多的开发人员采用 MCP,您可以期待看到越来越多的服务器和工具可用于与您的项目集成。
在 VS Code 中启用 MCP 支持
VS Code 中从 VS Code 1.102 开始通常支持 MCP,但您的组织可以禁用它。
集中管理 MCP 支持
您有两种选择来集中管理组织中的 MCP 支持
-
设备管理:通过组策略或配置配置文件在组织中集中启用或禁用 MCP 支持。了解更多关于使用设备管理管理 VS Code 设置的信息。
-
GitHub Copilot 策略:使用 GitHub Copilot 策略控制组织中 MCP 服务器的可用性。了解更多关于 GitHub Copilot 文档中管理企业中 Copilot 的策略和功能的信息。
添加 MCP 服务器
您有多种选项可以在 VS Code 中添加 MCP 服务器
- 直接安装:访问精心策划的 MCP 服务器列表,并在任何 MCP 服务器上选择安装以自动将其添加到您的 VS Code 实例。
- 工作区设置:在您的工作区中添加一个
.vscode/mcp.json
文件以配置作用于工作区的 MCP 服务器。 - 用户设置:在您的用户配置中指定服务器(MCP: 打开用户配置)以在所有工作区中启用 MCP 服务器,并通过设置同步进行同步。
- 自动发现:启用自动发现 (chat.mcp.discovery.enabled) 其他工具(如 Claude Desktop)中定义的 MCP 服务器。
要查看和管理已配置的 MCP 服务器列表,请从命令面板运行MCP: 显示已安装的服务器命令,或访问扩展视图中的MCP 服务器 - 已安装部分。
当 VS Code 首次启动 MCP 服务器时,它会发现服务器的功能和工具。然后您可以在代理模式下使用这些工具。VS Code 缓存 MCP 服务器的工具列表。要清除缓存的工具,请在命令面板中使用MCP: 重置缓存工具命令。
MCP 服务器可以在您的机器上运行任意代码。只从受信任的来源添加服务器,并在启动前审查发布者和服务器配置。当您首次启动 MCP 服务器时,VS Code 会提示您确认信任 MCP 服务器。
将 MCP 服务器添加到您的工作区
要为特定工作区配置 MCP 服务器,您可以在工作区文件夹中创建一个 .vscode/mcp.json
文件。这允许您与项目团队成员共享服务器配置。
确保通过使用输入变量或环境文件来避免硬编码敏感信息,例如 API 密钥和其他凭据。
要将 MCP 服务器添加到您的工作区
-
在您的工作区中创建一个
.vscode/mcp.json
文件。 -
选择添加服务器按钮以添加新服务器的模板。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/github/github-mcp-server/ "Github": { "url": "https://api.githubcopilot.com/mcp/" }, // https://github.com/ppl-ai/modelcontextprotocol/ "Perplexity": { "type": "stdio", "command": "npx", "args": ["-y", "server-perplexity-ask"], "env": { "PERPLEXITY_API_KEY": "${input:perplexity-key}" } } } }
-
或者,从命令面板运行MCP: 添加服务器命令,选择要添加的 MCP 服务器类型并提供服务器信息。接下来,选择工作区设置以在您的工作区中创建
.vscode/mcp.json
文件(如果它尚不存在)。
将 MCP 服务器添加到您的用户配置
要为所有工作区配置 MCP 服务器,您可以将服务器配置添加到您的用户配置中。这允许您在多个项目中重用相同的服务器配置。
要将 MCP 添加到您的用户配置,请运行MCP: 打开用户配置命令,该命令将在您的用户配置文件中打开 mcp.json
文件。如果文件不存在,VS Code 将为您创建它。
或者,从命令面板使用MCP: 添加服务器命令,提供服务器信息,然后选择全局将服务器配置添加到您的配置文件。
当您使用多个 VS Code 配置文件时,这允许您根据您的活动配置文件在不同的 MCP 服务器配置之间切换。例如,Playwright MCP 服务器可以在 Web 开发配置文件中配置,但不能在 Python 开发配置文件中配置。
开发容器支持
MCP 服务器可以通过 devcontainer.json
文件在开发容器中配置。这允许您将 MCP 服务器配置作为容器化开发环境的一部分。
要在开发容器中配置 MCP 服务器,请将服务器配置添加到 customizations.vscode.mcp
部分
{
"image": "mcr.microsoft.com/devcontainers/typescript-node:latest",
"customizations": {
"vscode": {
"mcp": {
"servers": {
"playwright": {
"command": "npx",
"args": ["-y", "@microsoft/mcp-server-playwright"]
}
}
}
}
}
}
创建开发容器时,VS Code 会自动将 MCP 服务器配置写入远程 mcp.json
文件,使其在您的容器化开发环境中可用。
MCP 服务器的自动发现
VS Code 可以自动检测并重用您在其他工具(例如 Claude Desktop)中定义的 MCP 服务器。
使用 chat.mcp.discovery.enabled 设置启用自动发现。
配置格式
使用以下 JSON 配置格式定义 MCP 服务器。
-
"servers": {}
包含 MCP 服务器列表,并遵循 Claude Desktop 的配置格式。
将服务器名称指定为键,并提供服务器配置作为值。VS Code 在 MCP 服务器列表中显示服务器名称。请遵循以下服务器名称的命名约定
- 服务器名称使用驼峰命名法,例如 "uiTesting"。
- 避免使用空格或特殊字符。
- 为每个服务器使用唯一名称以避免冲突。
- 使用描述性名称,反映服务器的功能或品牌,例如 "github" 或 "database"。
在服务器配置中提供以下字段。您可以在服务器配置中使用预定义变量,例如引用工作区文件夹 (
${workspaceFolder}
)。stdio
的服务器配置字段 描述 示例 类型
服务器连接类型。 "stdio"
命令
启动服务器可执行文件的命令。该命令需要在您的系统路径上可用,或包含其完整路径。
如果您使用 docker,请不要使用分离选项。"npx"
,"node"
,"python"
,"docker"
args
传递给命令的参数数组。 ["server.py", "--port", "3000"]
env
服务器的环境变量。 {"API_KEY": "${input:api-key}"}
envFile
.env
文件的路径,用于加载额外的环境变量。"${workspaceFolder}/.env"
sse
或http
的服务器配置字段 描述 示例 类型
服务器连接类型。VS Code 首先尝试可流式 HTTP 传输,如果 HTTP 不支持,则回退到 SSE。 "http"
,"sse"
url
服务器的 URL。 "https://:3000"
headers
服务器的 HTTP 头。 {"API_KEY": "${input:api-key}"}
-
"inputs": []
允许您定义配置值的自定义占位符,以避免在服务器配置中硬编码敏感信息(如 API 密钥或密码)。
当服务器首次启动时,VS Code 会提示您输入这些值,并安全地存储它们以供后续使用。为避免显示输入值,请将
password
字段设置为true
。了解更多关于如何在 VS Code 中配置输入变量的信息。
配置示例
以下代码片段显示了一个 MCP 服务器配置示例,该示例指定了三个服务器并为 API 密钥定义了一个输入占位符。
查看 .vscode/mcp.json
// 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/github/github-mcp-server/
"Github": {
"url": "https://api.githubcopilot.com/mcp/"
},
// https://github.com/modelcontextprotocol/servers/tree/main/src/fetch
"fetch": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
在代理模式中使用 MCP 工具
添加 MCP 服务器后,您可以在代理模式下使用它提供的工具。
在代理模式下使用 MCP 工具
-
打开聊天视图 (⌃⌘I (Windows, Linux Ctrl+Alt+I)),并从下拉菜单中选择代理模式。
-
选择工具按钮以查看可用工具列表。
可选地,选择或取消选择您要使用的工具。您可以通过在搜索框中键入来搜索工具。
重要一个聊天请求一次最多只能启用 128 个工具。如果选择的工具超过 128 个,请通过在工具选择器中取消选择一些工具来减少工具数量,或确保已启用虚拟工具 (github.copilot.chat.virtualTools.threshold)。
-
您现在可以在聊天输入框中输入提示,并注意工具如何根据需要自动调用。
默认情况下,当调用工具时,您需要先确认操作才能运行。这是因为工具可能在您的机器本地运行,并可能执行修改文件或数据的操作。
使用继续按钮下拉选项自动确认当前会话、工作区或所有未来调用的特定工具。
提示您还可以通过键入
#
后跟工具名称来直接在提示中引用工具。您可以在所有聊天模式(询问、编辑和代理模式)中执行此操作。 -
可选地,在运行工具之前验证和编辑工具输入参数。
使用 MCP 引导
MCP 服务器可以通过引导请求您提供额外的输入。当 MCP 服务器需要更多信息来完成任务时,它会提示您提供特定详细信息,例如确认、配置值或操作所需的其他参数。
当 MCP 服务器发送引导请求时,VS Code 会向您显示一个对话框或输入字段,您可以在其中提供所需信息。这允许 MCP 服务器动态收集必要数据,而无需提前设置所有配置。
使用 MCP 资源
除了工具之外,MCP 服务器还可以提供您可以在聊天提示中用作上下文的资源。例如,文件系统 MCP 服务器可能提供对文件和目录的访问,或者数据库 MCP 服务器可能提供对数据库表的访问。
要从 MCP 服务器将资源添加到您的聊天提示中
-
在聊天视图中,选择添加上下文 > MCP 资源
-
从列表中选择一个资源类型并提供可选的资源输入参数。
要查看 MCP 服务器的可用资源列表,请使用MCP: 浏览资源命令,或使用MCP: 列出服务器 > 浏览资源命令来查看特定服务器的资源。
MCP 工具可以返回资源作为其响应的一部分。您可以使用保存按钮或将资源拖放到资源管理器视图来查看或保存这些资源到您的工作区。
使用 MCP 提示
MCP 服务器可以为常见任务提供预配置的提示,这样您就不必键入详细的聊天提示。您可以通过在聊天输入框中键入 /
后跟提示名称(格式为 mcp.servername.promptname
)来直接调用这些提示。可选地,提示可能会要求您提供额外的输入参数。
将相关工具分组到工具集
随着您添加更多的 MCP 服务器,工具列表可能会变得很长。这使得管理单个工具变得很麻烦,例如当您想要定义一个可重用提示文件或自定义聊天模式时。
为了帮助您管理工具,您可以将相关工具分组到一个工具集中。工具集是单个工具的集合,您可以将其作为一个单一实体引用。工具集可以包含内置工具、MCP 工具或扩展提供的工具。
了解更多关于如何在 VS Code 中创建和使用工具集的信息。
管理 MCP 服务器
您可以从 VS Code 中扩展视图 (⇧⌘X (Windows, Linux Ctrl+Shift+X)) 中的MCP 服务器 - 已安装部分管理已安装的 MCP 服务器列表。这个专用视图使您可以轻松监控、配置和控制已安装的 MCP 服务器。
右键单击 MCP 服务器或选择齿轮图标以执行以下操作
- 启动/停止/重启:启动、停止或重启 MCP 服务器。
- 断开帐户:断开用于与 MCP 服务器进行身份验证的帐户。
- 显示输出:查看服务器日志以诊断问题。
- 显示配置:查看 MCP 服务器配置。
- 配置模型访问:配置 MCP 服务器可以访问哪些模型(采样)。
- 显示采样请求:查看 MCP 服务器发出的采样请求。
- 浏览资源:查看 MCP 服务器提供的资源。
- 卸载:从您的环境中卸载 MCP 服务器。
或者,从命令面板运行MCP: 列出服务器命令以查看已配置的 MCP 服务器列表。然后您可以选择一个服务器并对其执行操作。
当您通过MCP: 打开工作区文件夹 MCP 配置打开 .vscode/mcp.json
文件时,VS Code 会显示直接从编辑器启动、停止或重启服务器的命令。
自动启动 MCP 服务器
当您添加 MCP 服务器或更改其配置时,VS Code 需要(重新)启动服务器才能发现它提供的工具。
您可以从聊天视图手动重新启动 MCP 服务器,或使用其他启动选项。
或者,使用 chat.mcp.autostart 设置(实验性)配置 VS Code,以便在检测到配置更改时自动重新启动 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 服务器可以在您的机器上运行任意代码。只从受信任的来源添加服务器,并在启动前审查发布者和服务器配置。
当您将 MCP 服务器添加到工作区或更改其配置时,您需要确认信任服务器及其功能才能启动它。当您第一次启动服务器时,VS Code 会显示一个对话框,确认您信任服务器。选择对话框中的 MCP 服务器链接以在新窗口中查看 MCP 服务器配置。
如果您不信任服务器,它将不会启动,聊天请求将继续而不使用服务器提供的工具。
您可以通过从命令面板运行MCP: 重置信任命令来重置 MCP 服务器的信任。
如果您直接从 mcp.json
文件启动 MCP 服务器,则不会提示您信任服务器配置。
跨设备同步 MCP 服务器
启用设置同步后,您可以在设备之间同步设置和配置,包括 MCP 服务器配置。这使您能够保持一致的开发环境并在所有设备上访问相同的 MCP 服务器。
要启用 MCP 服务器与设置同步的同步,请从命令面板运行设置同步: 配置命令,并确保MCP 服务器包含在同步配置列表中。
故障排除和调试 MCP 服务器
MCP 输出日志
当 VS Code 遇到 MCP 服务器问题时,它会在聊天视图中显示错误指示器。
选择聊天视图中的错误通知,然后选择显示输出选项以查看服务器日志。或者,从命令面板运行MCP: 列出服务器,选择服务器,然后选择显示输出。
调试 MCP 服务器
您可以通过向 MCP 服务器配置添加 dev
键来启用 MCP 服务器的开发模式。这是一个包含两个属性的对象
watch
:一个文件 glob 模式,用于监视文件更改,这将重新启动 MCP 服务器。debug
:使您能够使用 MCP 服务器设置调试器。
{
"servers": {
"gistpad": {
"command": "node",
"args": ["build/index.js"],
"dev": {
"watch": "build/**/*.js",
"debug": { "type": "node" }
},
我们目前仅支持调试分别使用 node
和 python
启动的 Node.js 和 Python 服务器。
常见问题
我可以控制使用哪些 MCP 工具吗?
是的,您有几个选项可以控制哪些工具处于活动状态
- 在代理模式下,选择聊天视图中的工具按钮,并根据需要打开/关闭特定工具。
- 通过使用添加上下文按钮或键入
#
将特定工具添加到您的提示中。 - 对于更高级的控制,您可以使用
.github/copilot-instructions.md
来微调工具使用。
使用 Docker 时 MCP 服务器未启动
验证命令参数是否正确,以及容器是否未以分离模式(-d
选项)运行。您还可以检查 MCP 服务器输出中的任何错误消息(参见故障排除)。
我收到一个错误,显示“每个请求不能有超过 128 个工具。”
由于模型限制,一个聊天请求一次最多只能启用 128 个工具。如果您选择的工具超过 128 个,请通过在聊天视图中的工具选择器中取消选择一些工具或整个服务器来减少工具数量,或确保已启用虚拟工具 (github.copilot.chat.virtualTools.threshold)。