私有API接入Claude Code的MCP配置与鉴权排查清单

一、先明确本文的边界

本文属于 search 型工程方法文章，目标是给出一套可执行的排查顺序与验证清单，而不是复述官方文档。

需要特别说明：本文不掌握 Claude Code 与 MCP 的官方一手资料，因此所有涉及具体命令、字段名、配置路径、传输方式的内容，一律标注为「需以官方文档为准的示例」，不得当作已确认的产品行为。工程侧的分析与建议，会明确标注为「可通过压测或抓包验证」「生产环境需进一步确认」。

二、接入私有 API 的四个高频故障面

把内部私有服务暴露给 Claude Code 使用，典型问题集中在四处：

1. 注册层：MCP server 没有被正确注册，或注册后未被识别。
2. 鉴权层：token 传递方式不匹配，或作用域过大。
3. schema 层：工具粒度过粗或过细，导致调用失败或误用。
4. 环境层：本地与容器下的路径、网络出口不一致。

下面按这个顺序给出排查清单。

三、注册与配置：先验证「能不能被发现」

排查顺序建议如下：

• 第一步：确认 server 进程本身可独立启动。 在接入 Agent 之前，先手动运行 MCP server，确认它能正常监听或响应。这一步与 Claude Code 无关，属于基础可用性验证。
• 第二步：确认注册入口。 不同版本可能通过命令行参数、独立配置文件或项目级配置注册。具体注册命令与配置文件路径需以官方文档为准，本文不给出确定字段名。
• 第三步：确认配置生效范围。 需要区分全局配置与项目级配置：项目级配置通常随仓库走，全局配置影响本机所有会话。这一区分方式需以官方文档为准，但「先确认作用域再排查」是通用工程原则。
• 第四步：查看日志。 注册失败通常会在启动日志或调试输出中留下痕迹。建议开启最详细的日志级别，观察 server 是否被加载、是否报错退出。

验证清单：server 可独立运行 → 注册入口明确 → 作用域确认 → 日志无加载错误。

四、鉴权 token：最小化与作用域隔离

这是「调通了但不安全」的主要来源。

通用工程原则（非产品事实）：

• 凭据最小化：给 MCP server 使用的 token 应只具备完成其任务所需的最小权限，避免使用全权限账号。
• 作用域隔离：不同内部服务使用不同凭据，避免一个 token 打通所有服务。
• 传递方式待核验：token 究竟通过环境变量、请求头还是配置文件字段传入，需以官方文档为准。在未确认前，不要假设某一种方式一定生效。
• 避免硬编码：无论最终采用哪种传递方式，都不应把 token 明文写入会提交到仓库的配置文件。

可通过抓包或日志验证：

• 实际发出的请求是否携带了预期凭据；
• 凭据是否被意外写入日志或错误信息；
• 请求失败时返回的是鉴权错误还是网络错误，二者排查方向完全不同。

五、工具 schema 粒度：粗与细的取舍

schema 粒度直接影响调用成功率与安全性。

• 过粗：一个工具承担过多职责，参数复杂，模型容易填错，且权限边界模糊。
• 过细：工具数量膨胀，模型选择困难，调用链变长。

建议的验证方式：

1. 先按业务动作拆分工具，每个工具对应一个明确意图。
2. 观察实际调用日志，统计哪些工具从未被正确调用。
3. 对高频误用的工具，考虑合并或重新命名参数。

需以官方文档为准的部分：schema 的具体字段定义、必填项规则、以及工具描述如何被模型消费，本文不给出确定结论。

六、本地与容器：路径与网络差异

这是「本地能跑、容器里调不通」的常见原因。

路径差异：

• 本地运行时，配置文件与凭据文件通常位于用户目录；容器内这些路径可能不存在或未挂载。
• 排查时先确认容器内实际可见的路径，再对照配置中引用的路径。

网络差异：

• 本地可能直连内部服务；容器内可能受网络策略限制，出口不同。
• 建议在容器内单独验证到目标服务的连通性，而不是假设与本地一致。

生产环境需进一步确认： 容器编排下的网络策略、凭据注入方式（如密钥管理服务）与本地差异较大，需结合具体部署环境验证。

七、一页排查清单

八、小结

接入私有 API 的核心不是记住某条命令，而是建立一套排查顺序：先确认能被发现，再确认凭据正确且最小化，然后调整 schema 粒度，最后处理环境差异。本文所有具体配置细节均需以官方文档为准，工程建议请结合自身环境验证后再用于生产。