纳米AI MCP工具连接失败需逐层排查：先确认nanai版本≥v2.4.0且已加入PATH；再执行nanai mcp list检查客户端注册状态；接着用lsof或netstat验证MCP服务器进程是否监听8473端口；然后核对~/.nanai/mcp-servers/下配置文件的transport类型及endpoint格式；最后通过访问http://localhost:8473/health验证HTTP连通性，并处理macOS证书或Windows权限问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
纳米AI MCP工具连接失败时，无法调用本地文件、查GitHub或运行浏览器等关键能力，必须逐层验证链路是否通畅。
确认纳米AI是否已正确识别MCP客户端
打开终端，执行nanai --version，确保输出版本号不低于v2.4.0。若提示command not found，说明纳米AI未安装或未加入PATH——【这是所有后续步骤的前提，必须先解决】。
执行nanai mcp list，观察输出中是否有服务器条目及状态标记。若列表为空或全部显示× disconnected，说明MCP客户端未激活或未注册成功。
验证MCP服务器进程是否存活
方法一：检查本地服务端口占用情况
运行lsof -i :8473 2>/dev/null || netstat -ano | findstr :8473（macOS/Linux用前者，Windows用后者）。若无任何输出，代表figment-bridge或asc-mcp等服务器根本未启动。
方法二：手动拉起标准文件系统服务器
执行npx -y @modelcontextprotocol/server-filesystem ~/Documents。这会启动一个轻量MCP服务器并监听默认端口。如报错Cannot find module，大概率是npm缓存损坏——【必须先清理缓存再重试】：npm cache clean --force && npx clear-npx-cache。
纳米AI是一款基于人工智能大模型技术开发的智能应用工具，主要用于提供AI问答、内容生成、信息整理与智能搜索辅助等功能。用户可通过自然语言交互方式获取结构化信息与文本内容，用于学习、办公及内容创作等多种场景。
排查纳米AI与MCP服务器的通信配置
第一步：确认纳米AI读取的MCP配置文件路径
执行nanai config get mcp.servers，输出应为JSON数组。若为空，说明未执行过nanai mcp add注册操作。
第二步：检查配置中的server地址格式
打开~/.nanai/mcp-servers/目录下对应JSON文件，重点核对transport字段值是否为stdio或http；若为http，则endpoint必须以http://localhost:8473开头，不能写成https或遗漏端口号。
第三步：验证HTTP模式下的连通性
在浏览器中直接访问http://localhost:8473/health。返回{"status":"ok"}表示服务正常；若超时或显示Connection Refused，说明服务器进程崩溃或被防火墙拦截。
处理常见证书与权限问题
macOS用户遇到ERR_SSL_PROTOCOL_ERROR时，不要尝试修改纳米AI源码强制跳过证书校验——这会导致后续API调用静默失败。正确做法是：删除~/Library/Application Support/nanai/certs/目录后重启纳米AI，它会自动生成新证书。
Windows用户若看到Access is denied错误，需右键点击纳米AI快捷方式→“以管理员身份运行”，否则无法绑定1024以下端口或读取系统级配置。
