MCP 配置优先级在不同终端和 IDE 中如何变化

MCP 配置冲突不是 MCP 本身的问题，而是客户端的问题。分清这一点，可以避免大量错误调试。

协议只规定客户端在启动服务器后如何与服务器通信。它不会告诉 Claude Code、VS Code、Cursor、GitHub Copilot CLI 或某个扩展应该先读取哪个 JSON 文件，两个同名条目是否合并，也不会规定插件能否在基于文件的配置加载后注册服务器。如果你假设所有客户端都有一套通用层级，就可能用看起来正确的工具名称，运行了错误的可执行文件。

这种故障很容易被忽略。工具列表显示 github，代理调用 github.search_code，调用也成功了。但与此同时，终端代理可能针对测试账户启动了项目包装器，而 IDE 启动的全局命令连接的是你的个人账户。名称匹配了，命令却没有匹配。

我采用的工作原则是：按客户端、按进程、按服务器名称解析 MCP 配置。将服务器命令、参数、环境变量、工作目录、传输 URL 和凭据来源视为一个完整的启动定义。不要根据代理面板中显示的标签推断其中任何一项。

MCP 没有共享的优先级阶梯

MCP 规定了客户端与服务器之间的消息和能力，但没有规定可移植的文件布局，也没有规定配置来源发生冲突时由谁胜出。客户端可以使用 JSON 文件、设置数据库、插件 API、企业托管策略、命令行标志，或者同时使用其中所有方式。

这意味着人们经常混用的四个说法并不等价：

• 用户配置是某个账户或配置文件的客户端专属全局定义。
• 项目配置是与代码仓库或工作区关联的定义。
• 插件配置是由已安装的扩展或插件注册或提供的服务器。
• 编辑器设置属于编辑器本身，可能控制 MCP 服务器配置，也可能完全不控制。

最后一个区别带来的麻烦比应有的更多。VS Code 有一套成熟的常规设置层级：对于普通设置，工作区设置覆盖用户设置，对象值可以合并，而基本类型和值数组会覆盖。这是 settings.json 的真实行为，但不能证明 .vscode/mcp.json 遵循相同的合并和冲突规则。VS Code 将 MCP 配置记录为单独的 mcp.json 文件，可以位于工作区或用户配置文件中。不要把设置引擎的假设带入另一种配置格式。

实际结论很直接：“工作区优先”在补充客户端名称、客户端版本、配置格式和具体冲突之前，并不是一个有用的答案。工作区文件可能添加一个服务器、遮蔽同名的全局服务器、与它共存，或者因为工作区不受信任而无法加载。这些是不同的结果，而通用的优先级图会把它们隐藏起来。

服务器名称是冲突的基本单位

大多数客户端会将 MCP 配置组织成映射：左边是服务器名称，右边是一份启动定义。客户端通常会使用这个映射键来判断两个声明是否冲突。

看下面两个文件：

// user configuration
{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["/Users/dev/bin/catalog-live.js"],
      "env": { "CATALOG_TARGET": "production" }
    }
  }
}

// project configuration
{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["./tools/catalog-fixture.js"],
      "env": { "CATALOG_TARGET": "fixture" }
    }
  }
}

人会看到两个 catalog 服务，客户端看到的却是 catalog 键对应的两个值。如果客户端选择其中一个定义，通常会选择完整定义。不要期待客户端把全局命令与项目参数组合起来，或者把项目命令与全局环境变量组合起来。有些设置系统会合并对象，但 MCP 客户端没有义务这样做。

这也是部分覆盖设计不理想的原因。需要不同端点的项目应完整声明自己需要的命令。需要个人工具的用户应使用不同名称。半覆盖会让你难以判断客户端究竟替换了整个服务器对象，还是以一种你没有测试过的方式合并了字段。

在诊断配置期间，使用能体现所有权和用途的名称：

{
  "mcpServers": {
    "catalog-user-live": { "command": "node", "args": ["/Users/dev/bin/catalog-live.js"] },
    "catalog-repo-fixture": { "command": "node", "args": ["./tools/catalog-fixture.js"] }
  }
}

这些名称不算优雅，但很诚实。等团队确定了唯一的规范定义，再将它重命名为 catalog。在此之前，简短的重复名称会把每次工具调用都变成猜谜。

还要区分重复名称和重复能力。两个服务器都可以提供名为 search 的工具，但只要服务器名称不同，它们仍然是不同的服务器。相似的描述可能让代理困惑，但客户端配置未必存在名称冲突。先解决客户端解析问题，再改进工具描述和命名。

Claude Code 有明确的 MCP 作用域顺序

Claude Code 是最容易判断的情况，因为它的 MCP 文档明确说明了同名服务器条目的顺序。本地作用域优先于项目作用域，项目作用域优先于用户作用域。它当前的术语很重要：local 是私有的、特定项目的默认作用域；project 会写入共享的 .mcp.json；user 适用于所有项目。Anthropic 过去曾为其中一些作用域使用不同名称，所以旧笔记和 shell 历史记录可能会误导你。

具体来说，如果三个作用域都包含 catalog，Claude Code 会启动本地定义。共享 .mcp.json 中的定义排在其后，用户定义则作为后备。

# private to this checkout and this user
claude mcp add catalog --scope local -- node ./tools/catalog-fixture.js

# shared with the repository
claude mcp add catalog --scope project -- node ./tools/catalog-service.js

# available in all repositories for this user
claude mcp add catalog --scope user -- node ~/bin/catalog-personal.js

预期的检查结果是只有一个名为 catalog 的生效服务器。当三个作用域都存在时，它应来自本地作用域。每次修改后，都运行用于列出或获取服务器的客户端命令，不要只相信刚编辑过的文件：

claude mcp get catalog

输出应标识服务器名称，并显示其配置的传输方式或命令详情。将实际的命令、参数和环境变量与预期定义进行比较。如果命令不是你刚编辑的那一条，就停止修改文件，找出哪个作用域仍然拥有这个名称。

不要将这条 MCP 作用域规则与 Claude Code 更广泛的设置优先级混为一谈。Anthropic 为常规 Claude Code 设置记录了企业托管策略、命令行参数、本地项目设置、共享项目设置和用户设置。托管设置可能限制 MCP 使用相关的外围行为，但不一定会作为第二份 MCP 服务器定义存在。这两套层级回答的是不同问题。

项目作用域还有一个陷阱。Claude Code 在使用 .mcp.json 提供的服务器前会请求批准。这个批准针对的是客户端是否可以使用项目提供的服务器，不会改变同名服务器配置的优先级。不要把批准提示理解为共享命令获胜的证据。

VS Code 将 MCP 文件与普通设置分开

VS Code 提供两个记录在案的 MCP 服务器配置位置：工作区中的 .vscode/mcp.json，以及用户配置文件中的 mcp.json，后者可以通过 MCP: Open User Configuration 命令打开。工作区文件适合通过源代码管理共享，配置文件则跟随用户，也可以因 VS Code 配置文件不同而不同。

这种布局很容易让人产生合理预期：代码仓库的配置应该定义仓库工具，配置文件应该定义个人工具。但这并没有单独记录完整的重名解析规则。特别是，公开的 MCP 配置参考文档介绍了架构和位置，却没有说普通 VS Code 设置优先级是否会逐字段应用于 servers 条目。

有经验的用户也会在这里走捷径。他们知道 VS Code 工作区设置会覆盖用户设置，于是在配置文件和工作区配置中写入相同的 MCP 服务器名称，修改项目命令，然后认定工作区命令必然会启动。它可能确实会启动，但根据相邻设置子系统得出的结论仍然只是结论，而不是文档明确保证的行为。

在 VS Code 中，将同名冲突视为必须测试的情况。让两个候选项明显不同，并使用一个无害的命令来证明到底是哪一个启动了：

{
  "servers": {
    "precedence-probe": {
      "type": "stdio",
      "command": "sh",
      "args": ["-lc", "printf 'workspace probe started\\n' >&2; exec node ./tools/probe-server.js"]
    }
  }
}

在用户配置文件中放入不同的标记：

{
  "servers": {
    "precedence-probe": {
      "type": "stdio",
      "command": "sh",
      "args": ["-lc", "printf 'profile probe started\\n' >&2; exec node $HOME/bin/probe-server.js"]
    }
  }
}

然后通过 VS Code 的 MCP 管理界面完全重启服务器。如果界面无法明确显示进程状态，就重启编辑器。在 MCP 服务器输出或日志中查看标记。不要使用真实数据库或真实部署目标进行测试。优先级检查应证明启动路径，而不是修改数据。

启用状态也需要同样谨慎。VS Code 说明启用和禁用状态与服务器配置分开存储，因此共享配置文件可能存在，但服务器不会在某个工作区中启动。“我能在 mcp.json 中看到它”和“这个客户端启动了它”是两个不同的事实。

多根工作区又增加了一个容易产生错误确定感的地方。VS Code 对常规设置有工作区和工作区文件夹作用域，但绑定到工作区的 MCP 文件并不会自动成为按文件夹划分的服务器声明。如果工具需要基于仓库的相对路径命令，就应在测试中明确工作区根目录和预期工作目录。编辑器打开多个文件夹时，在一个根目录中有效的命令，可能会失败，或者悄悄访问另一个文件。

Cursor 同时存在项目、全局和扩展注册路径

Cursor 将项目专属 MCP 配置记录在 .cursor/mcp.json，将全局配置记录在 ~/.cursor/mcp.json。它还提供扩展 API，可以通过程序注册 MCP 服务器。这是三个不同来源：仓库文件、用户文件，以及扩展内部运行的代码。

当名称唯一时，前两个来源很容易理解。将仓库共享的开发服务放入 .cursor/mcp.json，将个人工具，例如本地笔记搜索服务，放入全局文件。Cursor CLI 表示会检测并使用 mcp.json，因此当 IDE 和终端代理确实运行在同一环境中时，共享配置很有用。

难点在于三个来源都出现重复名称。Cursor 的公开 MCP 文档告诉你项目文件和全局文件应放在哪里，但没有发布涉及全局配置、项目配置和动态注册扩展服务器的完整冲突规则。不要从论坛帖子、过时的发行说明或某台机器上的观察结果中臆造规则。

安全的设计是避免冲突。如果某个扩展提供 issue-tracker，就不要在 .cursor/mcp.json 中再写第二个 issue-tracker 条目，然后期待仓库命令替换它。为仓库所有的服务器使用另一个名称，例如 issue-tracker-fixture，并在代理指令或工具描述中说明何时应使用它。

对于同时使用插件和文件的团队，这一点尤其重要。插件可能自行处理安装、OAuth、更新或注册，时间也由它自己决定。仓库文件则能在代码审查中看到。这是两种不同的所有权模式。在试图让它们碰巧保持一致之前，先决定由谁拥有这个服务器。

环境边界会让 Cursor 冲突看起来更加奇怪，但本质并不复杂。桌面编辑器可能运行在一个操作系统上，而它的终端、远程工作区或开发容器可能运行在另一个环境中。某个主目录中的全局文件可能只存在于其中一个环境。项目文件中的命令可能通过不同的 PATH 找到不同的 node、python 或相对路径可执行文件。在讨论优先级之前，先写清楚客户端进程运行在哪里，以及服务器进程运行在哪里。

为每个候选项记录这份简短的启动信息：

client: Cursor desktop / Cursor CLI
client environment: local macOS / WSL / remote host / container
config source: ~/.cursor/mcp.json / .cursor/mcp.json / extension registration
server name: issue-tracker
command: node ./tools/issue-mcp.js
working directory: repository root
credential source: OAuth / local environment / external gateway

花五分钟记录这些信息，比花一下午反复切换设置面板更有用。

GitHub Copilot CLI 记录了项目优先于用户的 MCP 解析规则

GitHub Copilot CLI 比许多客户端更加明确。其文档说明，.mcp.json 或 .github/mcp.json 中的项目级 MCP 配置优先于 ~/.copilot/mcp-config.json 中同名的定义。这是 CLI 针对 MCP 服务器名称明确记录的项目优先于用户规则。

应将它作为客户端专属规则，而不是 GitHub Copilot 在每个编辑器中的通用事实。Copilot CLI 有自己的配置目录、仓库设置、本地设置、插件支持、权限存储和命令行进程。VS Code 中的 Copilot 会话是另一个客户端界面，拥有自己的 MCP 配置文档和生命周期。

一个整洁的 Copilot CLI 配置可以这样写：

// ~/.copilot/mcp-config.json
{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["/Users/dev/bin/company-docs-mcp.js"]
    },
    "catalog": {
      "command": "node",
      "args": ["/Users/dev/bin/catalog-live.js"]
    }
  }
}

// .mcp.json in the repository
{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["./tools/catalog-fixture.js"]
    }
  }
}

在这个仓库中，Copilot CLI 应使用项目中的 catalog 定义，同时保留用户级的 docs 定义，因为项目中没有与 docs 冲突的条目。这是一个有用的模型：只覆盖项目拥有的名称，让无关的个人工具继续保留。

插件会让情况变得复杂，因为插件可以带来自己的代理行为和 MCP 服务器生命周期。GitHub 的配置文档说明，仓库启用的插件属于仓库作用域；当仓库不再启用插件时，客户端会关闭插件的 MCP 服务器。这说明插件的服务器与插件激活状态绑定，并不是简单地复制到用户 MCP 文件中。

如果插件提供的服务器和文件提供的服务器使用相同名称，不要猜哪个命令会获胜。检查 CLI 显示的服务器状态、插件状态和启动输出。如果已安装版本的文档没有说明冲突行为，就重命名其中一个定义，或移除其中一个提供方。“直接在仓库中覆盖插件服务器”的建议很有吸引力，因为它简短，但当插件在文件加载后拥有注册权，或提供额外的生命周期状态时，这个建议就可能是错的。

编辑器和终端是不同的 MCP 客户端

IDE 内置的终端看起来像编辑器的一部分，但它仍然是一个 shell 进程。当你运行 claude、copilot 或 cursor-agent 时，这个命令可以读取自己的文件、当前目录、环境变量、主目录和配置覆盖变量。编辑器中的聊天扩展则是另一个进程，使用另一套客户端实现。

这就是人们经常报告“IDE 中的 MCP 服务器可以用，但终端中不行”的原因。常见解释包括：

• 编辑器打开了工作区文件，而终端启动在子目录或另一个检出目录中。
• 编辑器使用远程主机或容器，而终端命令在本地运行。
• 终端继承了 shell 专属的 PATH、HOME、代理设置或凭据变量。
• 编辑器激活了 CLI 不会加载的插件服务器。
• CLI 找到了同名的项目服务器，并替换了用户级条目。

不要一开始就把每个配置文件复制到每个位置。这样只会扩大冲突范围，并掩盖最初的原因。

应一次运行一个客户端并收集证据。对于终端客户端，使用内置命令列出或获取 MCP 服务器。对于编辑器客户端，使用 MCP 服务器管理视图及其输出或日志。记录服务器名称、命令、参数、进程位置和启动时间。如果终端和编辑器显示相同名称但命令不同，就找到了配置解析问题。如果它们显示相同命令但行为不同，就检查工作目录、凭据、网络访问或服务器本身。

一个有用的测试方法是暂时将目标服务器命令替换为一个包装器，在执行真正的服务器之前向标准错误输出写入明确标记。保持测试只读，完成后移除包装器。

#!/bin/sh
printf '%s client=%s cwd=%s\n' \
  "MCP probe started" \
  "${MCP_CLIENT_LABEL:-unknown}" \
  "$PWD" >&2
exec node "$(dirname "$0")/real-server.js"

不要打印令牌、请求头、凭据值、完整环境变量转储或请求载荷。日志往往会在终端会话结束后继续存在，优先级探针不应在解释一个秘密时制造新的泄露。

插件注册不是配置文件覆盖

插件是服务器配置的提供方，不只是另一个恰好存放 JSON 的文件夹。它可能动态注册服务器、管理身份验证、选择版本、响应工作区变化，或者在插件停用时停止服务器。

这会让两个常见建议变得不安全。

第一种建议是“在项目文件中使用相同名称来覆盖插件”。只有当客户端明确记录文件在插件之后加载，并且同名冲突会替换插件注册时，这种方式才有效。没有这份保证，重复条目可能导致错误、隐藏式替换、两个描述相似的工具，或者在更新后发生变化的行为。

第二种建议是“在界面中禁用服务器，项目就干净了”。启用状态可能存储在共享文件之外。VS Code 明确将启用或禁用状态与 MCP 配置分开。队友可以克隆同一个仓库，得到同一个文件，却仍然拥有不同的活动服务器集合。

应改用以下一种所有权模式：

1. **文件所有的服务器：**仓库提交服务器定义。所有人使用这个文件，并且没有插件注册同一服务。
2. **插件所有的服务器：**插件管理注册和身份验证。仓库不声明重复条目。
3. **分开的服务器角色：**插件拥有 tracker-live，项目文件拥有 tracker-fixture。名称、描述和权限明确区分两个目标。

第三种选择通常最不花哨，但最安全。团队经常需要同时使用个人的线上服务和仓库测试夹具。因为它们都连接问题跟踪器，就假装它们是同一台服务器，只会增加意外发起线上调用的可能性。

用可重复的方法证明哪个命令获胜

不依赖代理行为，也可以证明配置解析结果。下面的方法使用无害的 stdio 服务器或包装器，既适用于客户端启动本地命令，也适用于客户端指向远程服务的情况。

构建双来源探针

选择一个服务器名称，例如 precedence-probe。只在你要比较的两个来源中定义它。让每个候选项在启动同一个无害测试服务器前输出不同的标记。

对于基于命令的服务器，区分所有重要部分：

{
  "mcpServers": {
    "precedence-probe": {
      "command": "sh",
      "args": ["-lc", "printf 'SOURCE=PROJECT CWD=%s\\n' \"$PWD\" >&2; exec node ./tools/probe.js"],
      "env": { "MCP_PROBE_SOURCE": "project" }
    }
  }
}

用户候选项应输出 SOURCE=USER，并指向另一个已知文件。如果客户端会隐藏、过滤环境变量，或启动一个过时进程，不要只依赖环境变量。在命令路径和输出中也加入可见标记。

重启服务器，而不只是聊天窗口

MCP 服务器通常是长期运行的子进程。在服务器仍然运行时编辑 JSON，并不能证明下一次请求会使用新配置。使用客户端提供的控制项停止并重启服务器。如果该控制项不明确，就完全关闭相关客户端并重新打开工作区。

然后先检查客户端日志。预期证据应类似这样：

MCP probe started
SOURCE=PROJECT
CWD=/path/to/repository

如果没有看到标记，客户端可能在启动进程前拒绝了配置，使用了远程传输，或让旧服务器继续运行。这个结果同样有价值，它将问题从“哪个配置获胜”缩小为“配置是否加载，以及客户端是否启动了进程”。

一次只改变一个边界

先在终端客户端中运行探针，再在 IDE 客户端中运行。建立基线后再改变当前工作目录。测量完仅使用文件的行为后，再禁用插件。先测试用户来源和项目来源，再加入本地覆盖或托管设置。

在仓库 issue 或团队笔记中保留一张简短的结果表：

表格应记录观察到的行为，而不是预期行为。团队可以根据观察结果采取行动，从另一个客户端复制来的图表只能算假设。

将凭据置于优先级竞争之外

命令冲突是执行问题，凭据冲突是安全问题。不要为了让某个命令运行，就把秘密扩散到项目、插件、用户和编辑器配置中。

提交到仓库的项目配置通常应该包含服务器命令、非敏感的端点信息，以及获取凭据的说明。它不应在 env 中包含长期有效的 bearer 令牌、不应包含所有队友都没有的 SSH 私钥路径，也不应包含能授予生产环境访问权限的自定义请求头值。项目文件会成为每次克隆以及每个被客户端允许使用它的代理的执行邀请。

如果服务器需要秘密，应选择与工作相符的凭据边界：

• 当服务器和客户端支持 OAuth，且用户应交互式授予访问权限时，适合使用 OAuth。
• 对个人服务器定义，适合使用本地密钥管理器或环境注入。
• 仓库测试夹具应使用权限范围狭窄的非生产凭据。
• 当代理需要请求执行某项操作，却不应接触底层 API 或 SSH 凭据时，适合使用操作网关。

这也是服务器命令看起来无害却可能很危险的地方。npx some-mcp-server 可能在不同机器上解析到不同的已安装版本。node ./tools/server.js 可能继承父进程中的 AWS_PROFILE、GH_TOKEN 或企业代理。项目声明可以接受审查，但实际凭据来源仍可能不可见。

当代理需要 HTTP 或 SSH 访问时，Sallyport 可以将 API 或 SSH 凭据保存在加密保险库中，而代理通过 sp mcp 垫片连接，只接收操作结果。这不会决定哪个客户端配置获胜，但能防止获胜的命令同时将原始凭据交给代理。

不要把配置优先级当作权限系统。项目定义可以选择一个命令，但不能证明该命令无需审查就应被允许执行。将批准、凭据存储和审计证据作为相互独立的控制措施。

让规范命令一目了然

团队需要能够直接回答一个问题：这个仓库的代理应该为这项服务启动哪个命令？如果答案隐藏在用户文件、插件行为、README 片段和编辑器设置之间，配置已经过于松散。

将规范的共享定义写在一个地方。为它设置稳定的服务器名称。说明哪些客户端支持它，以及哪个来源拥有它。个人变体使用不同名称。如果插件必须拥有这项服务，就记录插件是规范来源，不要同时发布竞争性的文件定义。

然后在仓库中保留一个简短的验证命令或探针。配置变更和部署脚本一样值得测试。启动错误的服务器命令后，它可能在代理说出任何话之前读取错误的文件、调用错误的端点，或继承错误的凭据。

有用的结果不是一张通用的优先级图，而是一套这样的配置：每个客户端都有一条可观察的启动路径，每个服务器名称都有一个所有者，没有人需要猜代理究竟会执行哪个命令。