排查前先建立基线，三个信号缺一即视为未接通：
- 客户端 MCP 设置里该 Server 显示 Connected（绿灯 / Tools 数量 > 0）
- 对话中能触发工具调用（界面会显示
list_directory、fetch之类的调用记录） - 返回的是真实数据（来自你的文件 / 数据库 / 网络），而不是模型编造的内容
最省事的验证方式：刚配置完先让它「列出当前目录的文件」。这一步能过，问题就只剩业务参数。
使用指南·MCP
MCP 连接失败排查指南
MCP Server 连不上、工具列表为空、调用报错？按状态检查、启动日志、环境变量、远程 transport 四步定位，覆盖 Cursor / Claude Code / VS Code 常见故障。
先确认「接通」长什么样
第一步：看启动日志（80% 的问题在这）
Server 秒退 = 配置或环境问题，日志会直接告诉你原因：
- Cursor：Settings → MCP 里点该 Server 的 View log
- Claude Code：启动时加
claude --debug，或看~/.claude/logs/ - VS Code：Output 面板选 MCP 相关频道
高频报错对照：
| 报错 | 原因 | 处理 |
|---|---|---|
command not found: npx / uvx | 命令不在 PATH | 用绝对路径，如 /usr/local/bin/npx；GUI 应用不读 shell rc 文件 |
Cannot find module / 包不存在 | 包名拼错或已改名 | 以 AgentHub 详情页的配置为准 |
econnrefused / 拉包超时 | 网络或镜像源 | 配置 npm/pypi 镜像，或改用远程托管端点 |
port is already allocated | 本地端口占用 | 换端口或杀掉旧进程 |
第二步：检查 JSON 与环境变量
- JSON 语法：逗号、引号、大括号成对；从网页复制时留意被替换成全角的引号
- args 拆分：命令参数必须逐个放进数组，
"args": ["-y", "pkg-name"]，不能写成"-y pkg-name" - 环境变量：API Key、连接串是否填在
env字段；值两边不要留空格；占位符记得替换 - 换行与注释：
mcp.json是标准 JSON，部分客户端不支持注释，排查时先去掉 - 改完配置重载窗口 / 重启客户端，多数客户端不会热加载
第三步：远程 Server（HTTP / SSE）专项
远程托管类 MCP（streamable-http / SSE）不走本地进程，故障模式不同：
- 端点可达性：先用
curl -i <endpoint>验证，401/403 通常是 Key 缺失或过期 - 鉴权方式：Header 里的
Authorization/ API Key 名称要与服务方文档完全一致 - 协议版本：老客户端可能不支持 streamable-http，只认 SSE，换 transport 再试
- 代理与网络策略：企业内网注意域名白名单与 TLS 拦截
国内网络访问海外托管端点不稳定时，优先换成 AgentHub 上带国内镜像 / 直连端点的同类服务。
连上了但结果不对？
- 工具列表为空：Server 正常但没注册工具，检查是否选错发行版（如同名包的 stdio 与 http 版）
- 调用被拒绝 / 无权限：多数平台侧问题——令牌 scope 不够，回官方文档核对所需权限再重新授权
- 输出像「编」的：模型没真正调用工具（提示里明确要求使用工具），或该工具确实失败被静默跳过——回日志找痕迹
- 仍解决不了：到 AgentHub 资源详情页查上游仓库 Issues，带上日志片段提问，效率最高