MCP工具调用失败需按服务端、客户端、配置三层次排查：先确保Server正常运行并输出监听日志，再检查纳米AI是否正确连接http://localhost:3000，最后验证工具注册与客户端兼容性（版本≥v2.4.1、禁用插件、切换nanohub模型源）。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
纳米AI中MCP工具调用失败时，无法触发文件读写、数据库查询或本地命令执行等操作，表现为“工具不可用”“No tools available”或长时间无响应，需按服务端、客户端、配置三层次逐项验证。
确认MCP Server是否真正运行成功
在终端中手动启动Server，不要依赖纳米AI自动拉起：
复制你的MCP Server启动命令（例如npx -y @modelcontextprotocol/server-filesystem ./workspace），粘贴进新终端窗口并回车执行。
观察终端输出：必须看到类似"MCP Server listening on port 3000"或"Registered 4 tools"的日志行；若只显示“Starting…”后停滞、报错或立即退出，说明Server未就绪。
常见失败原因：当前目录权限不足导致server-filesystem无法扫描文件；PostgreSQL连接串漏写sslmode=disable参数引发握手失败；Node.js版本低于18.17会触发@modelcontextprotocol/server-*包的ESM加载异常。遇到任一情况，【必须先解决Server终端报错，再回到纳米AI】。
检查纳米AI是否识别到MCP服务
打开纳米AI → 设置 → MCP服务管理 → 查看“已启用服务”列表。
若列表为空或显示“未连接”，点击右侧「+ 添加服务」→ 手动输入Server地址，格式必须为http://localhost:3000（不能省略http://，不能写127.0.0.1）。
添加后等待5秒，状态栏应从“Connecting…”变为绿色“Connected”。若仍为灰色“Disconnected”，说明纳米AI网络策略拦截了本地回环请求——此时需关闭系统代理，或在纳米AI设置中开启「允许本地HTTP服务」开关。
纳米AI是一款基于人工智能大模型技术开发的智能应用工具，主要用于提供AI问答、内容生成、信息整理与智能搜索辅助等功能。用户可通过自然语言交互方式获取结构化信息与文本内容，用于学习、办公及内容创作等多种场景。
验证工具是否被正确注册与过滤
方法一：直查Server注册表
在Server运行状态下，浏览器访问http://localhost:3000/tools，返回JSON数组应包含至少一个tool对象，且name字段非空、description长度＞10字符。若返回空数组或404，说明Server未加载任何工具模块。
方法二：强制刷新工具缓存
纳米AI中长按MCP工具按钮（如「Read file」）2秒 → 弹出菜单选「重新发现工具」→ 等待进度条走完。这一步绕过客户端缓存，直接向Server发起/tools请求。
注意：若Server返回的tool列表中存在多个名称含“file”的工具（如read_file和read_local_file），纳米AI可能因模型混淆而主动屏蔽全部——此时需登录Server配置文件，删减冗余tool定义，保留唯一明确的read_file入口。
排查纳米AI专属兼容问题
第一步：确认纳米AI客户端版本 ≥ v2.4.1。
旧版本存在MCP Client解析annotations字段时崩溃的bug，会导致工具元数据丢失，表现为你明明在Server里写了"annotations": {"category":"file"}，但纳米AI始终不显示该工具。
第二步：临时禁用所有插件。
设置 → 插件管理 → 关闭「PDF解析增强」「代码高亮渲染」等第三方插件，这些插件会劫持MCP响应流并意外截断tool schema JSON。
第三步：切换模型源为nanohub。
设置 → 高级 → 模型源 → 选择「nanohub」→ 点击刷新图标。部分企业网络会干扰MCP服务发现阶段的DNS解析，nanohub节点内置MCP工具预注册机制，可跳过动态发现环节直接加载。
