Claude Code 如何发现并连接 MCP 服务

给 Claude Code 配好 MCP server，为什么还是用不了？这篇文章把「填一条配置」到「模型获得能力」之间的过程拆开了：先决定读取哪份配置，再建立连接、处理认证、完成握手和能力协商，最后才轮到能力进入模型可用的范围。

它最有用的地方，是把几类容易混在一起的问题分开：团队共享配置不等于共享凭据，同名配置覆盖不等于字段合并，连接成功也不等于工具已经可用。读懂这些边界，排查时就能少走几轮「改配置、重启、再试」。

团队共享 Jira，配置和凭据该放在哪里

作者沿用内部 Jira server 的例子：团队都需要访问同一个服务，但每个人的 API token 不能跟着代码进入仓库。Claude Code 因此需要区分配置的归属和作用范围。

原文列出了三种常规 scope，以及组织管理配置：

• Project scope 放在项目根目录的 .mcp.json，适合提交到版本控制，共享服务名称、地址和启动方式。
• User scope 放在 ~/.claude.json，对当前用户的所有项目生效，适合与某个仓库无关的个人服务。
• Local scope 也放在 ~/.claude.json，但按项目保存，只对指定项目生效，其他项目看不到。
• Managed configuration 由管理员集中提供，个人用户不能直接修改这份组织配置。

这里最容易混淆的是 Project 和 Local：前者属于仓库，可以跟团队共享；后者虽然针对某个项目，却属于个人私有配置。

对 Jira 这样的集成，仓库可以声明团队采用哪个服务，开发者再保留自己的凭据。不过，原文后面还有一个重要限制：如果个人通过 Local scope 配置了同名服务，它会替换项目中的完整定义，而不是只补上 token。因此，不能把两份配置想象成可以自动拼装的模板。

原文还提到两条额外入口：会话可以通过命令行选项接收临时配置，Claude.ai 中配置的 connectors 也可以进入 Claude Code。但没有给出具体选项名称，也没有完整解释它们与常规 scope 的冲突关系，这部分不能据此推导出操作命令。

同名服务出问题，先查整条配置来自哪里

同名 MCP server 的配置冲突，按整条定义覆盖，不按字段合并。

假设项目配置里有一个 Jira server，个人又在 Local scope 中声明了同名服务。按照原文，Claude Code 会使用 Local 中的完整条目，不会保留项目里的地址，再从个人配置里抽出一个认证 header。

这直接影响排查顺序。遇到地址不对、启动参数异常或认证配置没生效，应该先确认当前采用了哪一份定义，再检查它的内容。只盯着仓库中的 .mcp.json，可能一直在修改一份没有被采用的配置。

不过，原文在优先级列表处存在明显缺漏：它说要给出公开的优先顺序，实际只留下了「Plugin-provided servers」一项。后文明确支持的结论是，Local 的同名定义覆盖 Project，组织管理的同名定义优先于前述来源。User、Project、Local 和插件之间的完整排序，这份材料没有列全，不能自行补齐。

项目配置还有一道单独的保护。.mcp.json 会跟着仓库流转，因此 Claude Code 在交互会话中使用项目级服务前，会请求用户批准，让连接命令和参数先被看见。User 和 Local 属于用户自己的私有配置，原文说它们不需要相同的首次使用批准步骤。

这项设计针对的是一个具体风险：克隆仓库后，仓库携带的配置可能要求启动本地进程。配置可共享，并不代表其中的启动行为应该自动执行。

握手成功，也还没到模型调用工具那一步

配置只表达「尝试连接这个服务」。后面至少还有连接、认证和能力协商几道关。

原文列出的连接状态包括已连接、连接失败、正在连接、已禁用和需要认证。它们对应不同处理方式：URL 错误、进程缺失、子进程崩溃，属于连接问题；OAuth 会话过期或权限不足，属于认证问题。把它们都压成一句「MCP 不可用」，会丢掉最有用的排查线索。

连接和工具调用也不宜共用同一种超时判断。连接长时间没有响应，可能说明服务没启动或配置有误；工具调用却可能正在执行耗时任务。作者提出了这个区分，但没有提供具体超时数值、参数或实测数据。

传输通道建立后，还要进行能力协商（capability negotiation）。大白话解释，就是双方先报出自己支持什么，再启用双方都能处理的功能。

MCP 的能力不只有 tools，还包括 resources 和 prompts。服务可以提供可调用工具，也可以只提供可读取资源。服务没有声明 tools，Claude Code 就不应请求工具列表；没有声明 resources，对应的资源读取行为就保持不可用。

连接成功只说明通道和能力范围已经确定，不能据此断言模型已经获得新工具。

文章把完整链路分成几个职责：配置选出候选服务，连接与握手建立可用关系，能力协商限定功能范围，后续层再把允许的能力暴露给 agent。工具如何进入 Claude Code 自己的工具列表，本文没有继续展开。

至于底层通道，作者只预告了两类情况：启动本地子进程，通过标准输入输出通信；或者通过网络传输访问远程服务。具体支持哪些路径、怎样重试，是下一篇的内容。

我的判断

这篇最有价值的判断，是把「能不能用」拆成了可以定位的阶段。对使用 AI 编程工具的团队，这比反复修改同一份配置更有帮助：配置来源错了、进程没起来、凭据失效、服务没有声明相应能力，处理方式各不相同。

整条覆盖也有明确取舍。相比字段合并，它更容易回答「最终到底用了什么」，不会生成一份来自多个位置的隐式组合；代价是个人覆盖可能需要重复维护服务定义。团队如果把 Local 当成只存秘密字段的补丁层，就会误解它的行为。

但文章更接近机制讲解，没有给出可复现的握手记录、错误日志、延迟数据或不同配置方案的对照实验。它没有展示作者实测验证了哪些环节，不能把所有叙述都当作实验结论。尤其是优先级列表缺失，使它不足以直接充当完整配置手册。

另外，文中的团队 Jira 方案只解释了配置归属，没有给出凭据注入的完整样例。它能帮助确定哪些内容应当共享，具体如何安全传入凭据，仍需要补齐实现细节。

能拿来做什么

• 给前端或全栈仓库接入团队 MCP 服务时，先确定服务属于 Project、User 还是 Local，并在团队说明中写清配置位置，避免个人项目设置意外影响其他仓库。
• 排查同名服务时，先确认最终生效的完整定义来自哪个 scope，再检查地址、启动方式和认证信息，不要假设 .mcp.json 会与个人配置逐字段合并。
• 调试本地 Node MCP server 时，先区分子进程是否成功启动、通道是否建立、是否需要认证，再检查握手后的能力声明，按失败阶段缩小范围。
• 服务显示已连接却没有预期工具时，继续检查它是否声明 tools，以及后续能力暴露环节；如果它只提供 resources，就不能仅凭连接成功期待出现可调用动作。